diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index ff21565d3..30f97f36a 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -1,8 +1,8 @@ -name: ci +name: ci on: push: branches: - - dev + - PE permissions: contents: write jobs: @@ -16,8 +16,8 @@ jobs: git config --global user.name "Choreo CI Agent" - uses: actions/setup-python@v5 with: - python-version: 3.x - - run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV + python-version: 3.12 + - run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV - uses: actions/cache@v4 with: key: mkdocs-material-${{ env.cache_id }} @@ -44,6 +44,34 @@ jobs: pip install mkdocs-glightbox==0.3.4 pip install mkdocs-include-markdown-plugin==1.0.0 pip install mkdocs-open-in-new-tab==1.0.3 - - run: mkdocs gh-deploy --config-file en/mkdocs.yml --force + - name: Build site developer + run: mkdocs build --config-file en/developer-docs/mkdocs.yml + - name: Build site platform-engineer + run: mkdocs build --config-file en/pe-docs/mkdocs.yml + - name: Create/fetch gh-pages-v2 + run: | + if git ls-remote --heads origin gh-pages-v2 | grep -q gh-pages-v2; then + git fetch origin gh-pages-v2 + git checkout gh-pages-v2 + else + git switch --orphan gh-pages-v2 + fi + - name: Create gh-pages-v2 branch developer subdirectory + run: | + rm -rf choreo/docs/developer # Clear existing directory if needed + mkdir -p choreo/docs/developer + cp -r en/developer-docs/site/developer/* choreo/docs/developer/ + - name: Create gh-pages-v2 branch platform-engineer subdirectory + run: | + rm -rf choreo/docs/platform-engineer # Clear existing directory if needed + mkdir -p choreo/docs/platform-engineer + cp -r en/pe-docs/site/platform-engineer/* choreo/docs/platform-engineer/ + - name: Push Changes to gh-pages-v2 + run: | + git add choreo/docs/developer/ + git commit -m "Update developer directory" + git add choreo/docs/platform-engineer/ + git commit -m "Deploy to platform-engineer directory" + git push origin gh-pages-v2 --force env: - GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} diff --git a/README.md b/README.md index fad101151..6604146f6 100644 --- a/README.md +++ b/README.md @@ -20,127 +20,67 @@ Before you contribute, read the following guidelines to understand how you can s We look forward to your contributions. -## Run the project locally with Devcontainers -This repository supports the VS Code dev containers feature, which allows you to create a consistent and isolated development environment inside a Docker container. To use this feature, you need to have the following pre requisites: - -- VS Code -- Docker installed on your system -- [Remote - Containers](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) extension for VS Code - -Once you have these installed, you can open the repository in VS Code and follow these steps: - -- Press F1 and select the Remote-Containers: Open Folder in Container... command. -- Select the repository folder and wait for the container to build and start. -- You can now edit, run, debug, and test your code inside the container. - -For more information on how to use VS Code dev containers, please refer to the official documentation: https://code.visualstudio.com/docs/remote/containers - -### Run MkDocs server locally - -To start the server and view the site on your local server, run the following command: - - ```shell - $ mkdocs serve - ``` - - > **NOTE:** - > - > If you want to make changes and see them on the fly, run the following command to start the server and view the site on your local server: - > 1. Navigate to the `mkdocs.yml` file. - > 2. Set the following configuration: - > ``` - > #Breaks build if there's a warning - > strict: false - > ``` - > 3. To start the server, make it load the changes, and display the changes faster, run the following command: - > - > `mkdocs serve --dirtyreload` - -2. To view the Choreo documentation site locally, open the following URL on a new browser window: +## Run the project locally with MkDocs - [http://localhost:8000/](http://localhost:8000/) +### Prerequisites +- Python 3 + - Setup guides: [MacOS](https://docs.python.org/3/using/mac.html), [Windows](https://docs.python.org/3/using/windows.html), [Linux](https://wiki.python.org/moin/BeginnersGuide/Download#:~:text=using/mac.html-,Linux,-On%20most%20Linux) +- Pip3 + - Once you install Python, Pip is most likely to be installed by default. If not, follow the [Pip installation guide](https://pip.pypa.io/en/stable/installation/) for instructions. +### Setting up the project -## Run the project locally - -### Step 1 - Install Python - -#### MacOS -If you are using macOS, you probably already have a version of Python installed on your machine. Run the following command to verify: - +#### Step 1: Clone the project ```shell -$ python --version -Python 2.7.2 +git clone https://github.com/[git-username]/docs-choreo-dev.git ``` -If your version of Python is 2.x.x, you need to install Python3. Follow the instructions in [this guide](https://docs.python-guide.org/starting/install3/osx/) to install Python3. - -Once you are done, you should see two versions of Python on your machine; python2 and python3. - -#### Ubuntu and other versions of Debian Linux - -Python 3 is pre-installed in these versions, which you can verify using the `python3 -V` command. Run `sudo apt install -y python3-pip` to install `pip` and verify using `pip3 -V`. - -### Step 2 - Install pip -> -> **INFO** -> -> If pip is not already installed on your machine, run `get-pip.py` to install pip. Then run the following command to install it: -> ```shell -> $ python get-pip.py -> ``` -> - -Pip is most likely installed by default. However, you may need to upgrade pip to the latest version: - +#### Step 2: Create a Virtual Environment +- Navigate to the project's root where the `requirements.txt` file is located at. ```shell -$ pip install --upgrade pip +cd docs-choreo-dev/en +``` +- Execute the following commands to create a virtual environment and activate it. +```python +python3 -m venv dev-env +source dev-env/bin/activate ``` -### Step 3 - Install the pip packages - -To clone the Choreo documentation GitHub repository and run the site on your local server, follow these steps: - -1. Fork `https://github.com/wso2/docs-choreo-dev`. -2. Navigate to the locatiion where you want to clone the repo and clone the forked repository. - - ```shell - $ git clone https://github.com/[git-username]/docs-choreo-dev.git - ``` - -3. Navigate to the directory where you cloned the repo. - - For example: - - ```shell - $ cd docs-choreo-dev// - ``` - - ```shell - $ cd docs-choreo-dev/en/ - ``` - -4. Install the required pip packages. +#### Step 3: Install dependancies +Execute the following command from the directory where the `requirements.txt` file is located at. +```python +pip3 install -r requirements.txt +``` - This step installs MkDocs together with the required theme, extensions, and plugins. +#### Step 4: Navigate to the project directory +Choreo documentation provides two perspectives: Developer and Platform Engineer. Each perspective is hosted on a separate server. To access the desired perspective, navigate to the corresponding project root. +- For Developer perspective: +```shell +cd en/developer-docs +``` +- For Platform Engineer perspective: +```shell +cd en/pe-docs +``` - - If you are using Python2, run the following command: +#### Step 5: Start the development server +```shell +mkdocs serve --dirtyreload +``` +Note: `--dirtyreload` flag is used to enable live reloading of the documentation site when changes are made to the source files. If you don't want to enable live reloading, you can remove this flag. +Choreo docs will be available locally on [http://localhost:8000/](http://localhost:8000/) - ```shell - $ pip install -r requirements.txt - ``` +### Proof Reading Documentation - - If you are using Python3, run the following command: +Prerequisites: +- [MdSpell](https://github.com/mtuchowski/mdspell) - ```shell - $ pip3 install -r requirements.txt - ``` -### Step 4 - Build Project -1. To build the code navigate to the en folder and run the following command: +#### Steps +1. Navigate to the `en` directory and run the following command: ```shell - $ ./serve.sh + ./serve.sh ``` This script will check spellings and incorrect links. @@ -152,40 +92,23 @@ Incorrect spellings will be highlighted in red. You can take one of the followin - Proceed with "Add to dictionary - case sensitive" to add the word to the dictionary for all files, but only match the exact case used. For instance, with the word "Microsoft," the word "microsoft" would not be considered correct. All exclusions will be stored in a .spelling file in the directory from which you run the command. - Choose resolutions consciously. -If there are no errors, proceed to the next step. +## Run the project locally with Dev Containers -### Step 5 - Run MkDocs -1. To start the server and view the site on your local server, run the following command: +This repository supports the VS Code dev containers feature, which allows you to create a consistent and isolated development environment inside a Docker container. To use this feature, you need to have the following pre requisites: - ```shell - $ mkdocs serve - ``` +- VS Code +- Docker installed on your system +- [Remote - Containers](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) extension for VS Code + +Once you have these installed, you can open the repository in VS Code and follow these steps: + +- Press F1 and select the Remote-Containers: Open Folder in Container... command. +- Select the repository folder and wait for the container to build and start. +- You can now edit, run, debug, and test your code inside the container. - > **NOTE:** - > - > If you want to make changes and see them on the fly, run the following command to start the server and view the site on your local server: - > 1. Navigate to the `mkdocs.yml` file. - > 2. Set the following configuration: - > ``` - > #Breaks build if there's a warning - > strict: false - > ``` - > 3. To start the server, make it load the changes, and display the changes faster, run the following command: - > - > `mkdocs serve --dirtyreload` - -2. To view the Choreo documentation site locally, open the following URL on a new browser window: - - [http://localhost:8000/](http://localhost:8000/) - -> **NOTE:** -> -> If you are using the `mkdocs serve --dirtyreload` command to run the MkDocs server, be sure to change the configuration in the `mkdocs.yml` file as follows before sending a pull request: -> -> `strict: true` +For more information on how to use VS Code dev containers, please refer to the official documentation: https://code.visualstudio.com/docs/remote/containers ## License diff --git a/en/.spelling b/en/.spelling index 6fa2395dc..0648e4a7b 100644 --- a/en/.spelling +++ b/en/.spelling @@ -108,6 +108,7 @@ WebApps cron deployment.toml subpath +helloworld codebase libs work-with-the-micro-integrator-runtime-in-choreo diff --git a/en/docs/administer/configure-a-custom-domain-for-your-organization.md b/en/developer-docs/docs/administer/configure-a-custom-domain-for-your-organization.md similarity index 70% rename from en/docs/administer/configure-a-custom-domain-for-your-organization.md rename to en/developer-docs/docs/administer/configure-a-custom-domain-for-your-organization.md index 14e824682..60c63687b 100644 --- a/en/docs/administer/configure-a-custom-domain-for-your-organization.md +++ b/en/developer-docs/docs/administer/configure-a-custom-domain-for-your-organization.md @@ -70,6 +70,48 @@ To add a custom domain for your organization, follow the steps given below: - Certificate chain file guidelines: - The chain file, which is essential for some clients to verify the authenticity of a server's SSL/TLS certificate, should contain your domain's SSL/TLS certificate (optional, as this can be provided via the certificate itself) and one or more intermediate certificates in the correct order, leading back to a root certificate. - All certificates in the chain should be X509 certificates in PEM format. +
For step-by-step instructions on constructing a certificate chain with a root certificate, click here + To construct a certificate chain with a root certificate, you must organize and combine the certificates in the correct sequence. A typical certificate chain consists of the following: + - **Root certificate**: The trusted self-signed certificate issued by the certificate authority (CA). + - **Intermediate certificates** (if any): Certificates issued by the root CA to subordinate CAs. + - **Leaf certificate**: Your end-entity certificate issued by the CA. This is an optional certificate that may be included within the chain or provided separately.

+ Follow these steps to construct the certificate chain: + 1. Obtain and organize your certificates in the correct order: + - **Leaf certificate**: The public certificate issued by the CA. This is optional and may be included within the chain or provided separately. + - **Intermediate certificates**: Obtain these from the CA, if applicable. + - **Root certificate**: Obtain this from the CA. If it is self-signed, it serves as the trust anchor. + 2. Combine the certificates into a single file in the following order: + - Leaf certificate: This is your public certificate issued by the CA. + - Intermediate certificates if applicable: Include these in the correct hierarchical order. + - Root certificate: Include this at the end of the file.

+ Use a text editor or a command-line tool to concatenate the certificates into one file, ensuring each certificate begins and ends with the proper markers. Also make sure the `BEGIN CERTIFICATE` and `END CERTIFICATE` markers appear on a new line: + ``` + -----BEGIN CERTIFICATE----- + + -----END CERTIFICATE----- + -----BEGIN CERTIFICATE----- + + -----END CERTIFICATE----- + -----BEGIN CERTIFICATE----- + + -----END CERTIFICATE----- + ``` + 3. Save the concatenated file. You can save it with a name such as `certificate_chain.pem`. + 4. Use the following command to verify that your certificate chain is constructed correctly: + ``` + openssl verify -CAfile .pem certificate_chain.pem + ``` + Replace `.pem` with the path to your root certificate or a bundle containing both the root and intermediate certificates. + 5. Once the certificate chain is verified, upload it via the Choreo Console: + ![Upload certificate chain](../assets/img/administer/configure-domain/upload-certificate-chain.png) + - If the constructed chain includes the leaf certificate, follow these steps: + - Upload the constructed certificate chain in the **TLS Certificate** field. + - Upload the private key file in the **TLS Key File** field. + - Do not upload a certificate chain file, as it is already included in the TLS certificate. + - If the constructed chain does not include the leaf certificate, follow these steps: + - Upload the leaf certificate in the **TLS Certificate** field. + - Upload the private key file in the **TLS Key File** field. + - Upload the constructed certificate chain in the **Certificate Chain File** field. To proceed with this step in this guide, click **Let's Encrypt**. diff --git a/en/docs/administer/configure-a-user-store-with-built-in-idp.md b/en/developer-docs/docs/administer/configure-a-user-store-with-built-in-idp.md similarity index 100% rename from en/docs/administer/configure-a-user-store-with-built-in-idp.md rename to en/developer-docs/docs/administer/configure-a-user-store-with-built-in-idp.md diff --git a/en/docs/administer/configure-an-external-idp/configure-asgardeo-as-an-external-idp.md b/en/developer-docs/docs/administer/configure-an-external-idp/configure-asgardeo-as-an-external-idp.md similarity index 100% rename from en/docs/administer/configure-an-external-idp/configure-asgardeo-as-an-external-idp.md rename to en/developer-docs/docs/administer/configure-an-external-idp/configure-asgardeo-as-an-external-idp.md diff --git a/en/docs/administer/configure-an-external-idp/configure-azure-ad-as-an-external-idp.md b/en/developer-docs/docs/administer/configure-an-external-idp/configure-azure-ad-as-an-external-idp.md similarity index 95% rename from en/docs/administer/configure-an-external-idp/configure-azure-ad-as-an-external-idp.md rename to en/developer-docs/docs/administer/configure-an-external-idp/configure-azure-ad-as-an-external-idp.md index 237e30f67..bf8a4cb77 100644 --- a/en/docs/administer/configure-an-external-idp/configure-azure-ad-as-an-external-idp.md +++ b/en/developer-docs/docs/administer/configure-an-external-idp/configure-azure-ad-as-an-external-idp.md @@ -24,7 +24,7 @@ Follow the steps below to add Azure AD as an IdP in Choreo: !!! info - In azure, there are two versions of access tokens available. By default, the IDP applications you create use the v1 access token. Therefore, if you intend to use the v1 access token, when providing the `Well-Known URL`, omit the v2.0 path segment from the URL. [Learn more](https://learn.microsoft.com/en-us/azure/active-directory/develop/access-tokens#token-formats) For example, convert `https://login.microsoftonline.com//v2.0/.well-known/openid-configuration`-> `https://login.microsoftonline.com//.well-known/openid-configuration` - - If you intend to work with v2.0, then the IDP application's manifest should be changed as explained in the [access tokendocumentation](https://learn.microsoft.com/en-us/azure/active-directory/develop/access-tokens#token-formats). + - If you intend to work with v2.0, then the IDP application's manifest should be changed as explained in the [access token documentation](https://learn.microsoft.com/en-us/azure/active-directory/develop/access-tokens#token-formats). 8. Leave the **Apply to all environments** checkbox selected. However, if you want to restrict the use of the external IdP to a certain environment, you can select them from the **Environments** list. 9. Review the endpoints and click **Next**. diff --git a/en/developer-docs/docs/administer/configure-approvals-for-choreo-workflows.md b/en/developer-docs/docs/administer/configure-approvals-for-choreo-workflows.md new file mode 100644 index 000000000..165d9924b --- /dev/null +++ b/en/developer-docs/docs/administer/configure-approvals-for-choreo-workflows.md @@ -0,0 +1,63 @@ +# Configure Approvals for Choreo Workflows + +Choreo allows you to configure approval processes for specific workflows within the platform. An approval process for a workflow ensures that critical or sensitive changes are properly managed and controlled. + +Choreo currently allows you to configure approvals for environment promotion and API subscription workflows. + +Configuring approvals for environment promotion allows authorized users to control components being promoted to a critical/production environment. + +Configuring approvals for the API subscription workflow allows you to create subscription plans that require approval before being activated. This feature allows you to control access to APIs by requiring administrative review and authorization of subscriptions before they become active. + +## Permissions to review and respond to approval requests + +Click the respective tab for details on permissions depending on the workflow for which you want to configure approvals: + +=== "Environment promotion" + + To review and respond to environment promotion approval requests, a user must have the following permissions. Administrators must ensure that users designated to review and respond to approval requests have these permissions: + + - **WORKFLOW-MANAGEMENT**: + - Approve component promotion requests: Grants access to review and approve the promotion of components to critical environments. + - **PROJECT-MANAGEMENT**: Grants access to view and approve workflow requests. This is the same permission used to update or delete projects. + +=== "API subscription" + + To review and respond to API subscription approval requests, a user must have the following permissions. Administrators must ensure that users designated to review and respond to approval requests have these permissions: + + - **WORKFLOW-MANAGEMENT**: + - Approve API subscriptions: Grants access to review and approve API subscription workflow requests. + - **PROJECT-MANAGEMENT**: + Grants access to view and approve workflow requests. This is the same permission used to update or delete projects. + +## Set up an approval process for a workflow + +To set up an approval process for a workflow, follow these steps: + +!!! note + - You must have administrator privileges in Choreo to configure workflow approvals. + - Administrators can designate specific roles and assignees to review and respond to requests associated with each workflow. + +1. Sign in to the [Choreo Console](https://console.choreo.dev/). +2. In the Choreo Console header, go to the **Organization** list and select your organization. +3. In the left navigation menu, click **Settings**. This opens the organization-level settings page. +4. Click the **Workflows** tab. +5. Click the edit icon corresponding to the workflow for which you want to configure an approval. +6. In the **Configure Workflow** dialog that opens, select roles and assignees to review and respond to workflow approval requests. + + - In the **Roles** field, select one or more roles depending on your preference. Any user assigned to these roles can review and respond to requests. + - In the **Assignees** field, select specific users who can review and approve workflow requests. Assignees can be any Choreo user, even if they are not assigned to a selected role. + + !!! info "Important" + Currently, there is no validation to ensure that the specified roles and assignees have the necessary permissions to review and respond to requests. If the [required permissions](#permissions-to-review-and-respond-to-approval-requests) are not correctly configured, some users may receive email notifications but will be unable to review the requests. + +7. Click **Save**. This configures and enables the approval process for the workflow. + +Once you enable the approval process for a workflow, see the following details on how to submit a request for approval and the approval process. Click the respective tab depending on the workflow for which you enabled the approval process: + +=== "Environment promotion" + + Once you configure an approval process for environment promotion, developers must [submit a request for approval to use the workflow](../develop-components/submit-and-manage-workflow-approval-requests.md). An authorized assignee must then [review and approve the request](./review-workflow-approval-requests.md) for a developer to proceed with the task related to the workflow. + +=== "API subscription" + + Once you configure an approval process for API subscription, administrators can select the **Approval required** checkbox to create or update subscription plans to require approval. For details, see [Create API Subscription Plans](../administer/create-api-subscription-plans.md). API consumers using these plans must request approval to proceed. For details, see step 7 in [Subscribe to an API with a Subscription Plan](../api-management/manage-api-traffic/subscribe-to-an-api-with-a-subscription-plan.md). An authorized approver must then [review and approve the request](./review-workflow-approval-requests.md) before the subscription is granted. diff --git a/en/docs/administer/configure-enterprise-login.md b/en/developer-docs/docs/administer/configure-enterprise-login.md similarity index 100% rename from en/docs/administer/configure-enterprise-login.md rename to en/developer-docs/docs/administer/configure-enterprise-login.md diff --git a/en/docs/administer/configure-self-sign-up.md b/en/developer-docs/docs/administer/configure-self-sign-up.md similarity index 100% rename from en/docs/administer/configure-self-sign-up.md rename to en/developer-docs/docs/administer/configure-self-sign-up.md diff --git a/en/docs/administer/control-access-in-the-choreo-console.md b/en/developer-docs/docs/administer/control-access-in-the-choreo-console.md similarity index 100% rename from en/docs/administer/control-access-in-the-choreo-console.md rename to en/developer-docs/docs/administer/control-access-in-the-choreo-console.md diff --git a/en/docs/administer/control-egress-traffic-for-your-organization.md b/en/developer-docs/docs/administer/control-egress-traffic-for-your-organization.md similarity index 100% rename from en/docs/administer/control-egress-traffic-for-your-organization.md rename to en/developer-docs/docs/administer/control-egress-traffic-for-your-organization.md diff --git a/en/docs/administer/create-api-subscription-plans.md b/en/developer-docs/docs/administer/create-api-subscription-plans.md similarity index 91% rename from en/docs/administer/create-api-subscription-plans.md rename to en/developer-docs/docs/administer/create-api-subscription-plans.md index 6772e2583..768394b74 100644 --- a/en/docs/administer/create-api-subscription-plans.md +++ b/en/developer-docs/docs/administer/create-api-subscription-plans.md @@ -20,6 +20,7 @@ To create an organization-level subscription plan, follow the steps given below: - In the **Name** field, you must specify a name to uniquely identify the subscription plan in various contexts. The value is editable only at the time you create the subscription plan. You cannot change the name after you create it. - The **Stop on Quota Reach** checkbox is selected by default when creating a subscription plan. When selected, requests return an HTTP 429 response if the request count exceeds the limit. If you clear the checkbox, requests are allowed even if the quota is exceeded. - Burst control protects your backend from sudden request spikes and manages API usage. It’s especially useful for subscription plans where the request count is enforced over a long period, to prevent consumers from using their entire quota too quickly. Ensure you select the **Burst Control** checkbox when the **Request Count Time Unit** is selected as **Hour** or **Day**. + - Select the **Approval required** checkbox if subscription requests made to this plan require administrator or API publisher approval to activate the plan. This allows for manual review and approval of a subscription before granting API access. ![Create subscription plan](../assets/img/administer/create-subscription-plan.png) diff --git a/en/docs/administer/customize-the-developer-portal.md b/en/developer-docs/docs/administer/customize-the-developer-portal.md similarity index 100% rename from en/docs/administer/customize-the-developer-portal.md rename to en/developer-docs/docs/administer/customize-the-developer-portal.md diff --git a/en/docs/administer/inviting-members.md b/en/developer-docs/docs/administer/inviting-members.md similarity index 100% rename from en/docs/administer/inviting-members.md rename to en/developer-docs/docs/administer/inviting-members.md diff --git a/en/docs/administer/manage-members-of-an-organization.md b/en/developer-docs/docs/administer/manage-members-of-an-organization.md similarity index 100% rename from en/docs/administer/manage-members-of-an-organization.md rename to en/developer-docs/docs/administer/manage-members-of-an-organization.md diff --git a/en/docs/administer/review-workflow-approval-requests.md b/en/developer-docs/docs/administer/review-workflow-approval-requests.md similarity index 100% rename from en/docs/administer/review-workflow-approval-requests.md rename to en/developer-docs/docs/administer/review-workflow-approval-requests.md diff --git a/en/docs/api-management/api-governance/default-rulesets/owasp_top_10_doc.md b/en/developer-docs/docs/api-management/api-governance/default-rulesets/owasp_top_10_doc.md similarity index 100% rename from en/docs/api-management/api-governance/default-rulesets/owasp_top_10_doc.md rename to en/developer-docs/docs/api-management/api-governance/default-rulesets/owasp_top_10_doc.md diff --git a/en/docs/api-management/api-governance/default-rulesets/wso2_api_design_guidelines_doc.md b/en/developer-docs/docs/api-management/api-governance/default-rulesets/wso2_api_design_guidelines_doc.md similarity index 100% rename from en/docs/api-management/api-governance/default-rulesets/wso2_api_design_guidelines_doc.md rename to en/developer-docs/docs/api-management/api-governance/default-rulesets/wso2_api_design_guidelines_doc.md diff --git a/en/docs/api-management/api-governance/default-rulesets/wso2_style_guidelines_doc.md b/en/developer-docs/docs/api-management/api-governance/default-rulesets/wso2_style_guidelines_doc.md similarity index 100% rename from en/docs/api-management/api-governance/default-rulesets/wso2_style_guidelines_doc.md rename to en/developer-docs/docs/api-management/api-governance/default-rulesets/wso2_style_guidelines_doc.md diff --git a/en/docs/api-management/api-policies/about-api-policies.md b/en/developer-docs/docs/api-management/api-policies/about-api-policies.md similarity index 100% rename from en/docs/api-management/api-policies/about-api-policies.md rename to en/developer-docs/docs/api-management/api-policies/about-api-policies.md diff --git a/en/docs/api-management/api-policies/apply-advanced-settings-on-mediation-policies.md b/en/developer-docs/docs/api-management/api-policies/apply-advanced-settings-on-mediation-policies.md similarity index 100% rename from en/docs/api-management/api-policies/apply-advanced-settings-on-mediation-policies.md rename to en/developer-docs/docs/api-management/api-policies/apply-advanced-settings-on-mediation-policies.md diff --git a/en/docs/api-management/api-policies/attach-and-manage-policies.md b/en/developer-docs/docs/api-management/api-policies/attach-and-manage-policies.md similarity index 100% rename from en/docs/api-management/api-policies/attach-and-manage-policies.md rename to en/developer-docs/docs/api-management/api-policies/attach-and-manage-policies.md diff --git a/en/docs/api-management/api-rate-limiting.md b/en/developer-docs/docs/api-management/api-rate-limiting.md similarity index 100% rename from en/docs/api-management/api-rate-limiting.md rename to en/developer-docs/docs/api-management/api-rate-limiting.md diff --git a/en/docs/api-management/control-api-visibility.md b/en/developer-docs/docs/api-management/control-api-visibility.md similarity index 100% rename from en/docs/api-management/control-api-visibility.md rename to en/developer-docs/docs/api-management/control-api-visibility.md diff --git a/en/docs/api-management/documents.md b/en/developer-docs/docs/api-management/documents.md similarity index 100% rename from en/docs/api-management/documents.md rename to en/developer-docs/docs/api-management/documents.md diff --git a/en/docs/api-management/lifecycle-management.md b/en/developer-docs/docs/api-management/lifecycle-management.md similarity index 100% rename from en/docs/api-management/lifecycle-management.md rename to en/developer-docs/docs/api-management/lifecycle-management.md diff --git a/en/docs/api-management/manage-api-traffic/assign-subscription-plans-to-apis.md b/en/developer-docs/docs/api-management/manage-api-traffic/assign-subscription-plans-to-apis.md similarity index 100% rename from en/docs/api-management/manage-api-traffic/assign-subscription-plans-to-apis.md rename to en/developer-docs/docs/api-management/manage-api-traffic/assign-subscription-plans-to-apis.md diff --git a/en/docs/api-management/manage-api-traffic/subscribe-to-an-api-with-a-subscription-plan.md b/en/developer-docs/docs/api-management/manage-api-traffic/subscribe-to-an-api-with-a-subscription-plan.md similarity index 71% rename from en/docs/api-management/manage-api-traffic/subscribe-to-an-api-with-a-subscription-plan.md rename to en/developer-docs/docs/api-management/manage-api-traffic/subscribe-to-an-api-with-a-subscription-plan.md index 7aa68f142..330959a93 100644 --- a/en/docs/api-management/manage-api-traffic/subscribe-to-an-api-with-a-subscription-plan.md +++ b/en/developer-docs/docs/api-management/manage-api-traffic/subscribe-to-an-api-with-a-subscription-plan.md @@ -10,7 +10,10 @@ To subscribe to an API with a subscription plan, follow the steps given below: 4. In the left navigation menu, click **Subscriptions**. 5. In the **Subscription Management** pane that opens, click **+ Add APIs**. 6. In the **Add APIs** pane that opens, select the API, API version, and subscription plan with which you want to subscribe to the API. -7. Click **Add Subscription**. +7. If the selected subscription plan requires administrator or API publisher approval to become active, click Request Subscription. Otherwise, click Add Subscription. If the selected subscription plan requires approval, your subscription will be shown as "Pending" until it is approved by an organization admin or the API publisher. + + !!! Note + If the subscription plan requires administrator or API publisher approval to become active, the subscription status will be set to Pending Creation until it is reviewed and approved. ![Add subscription](../../assets/img/api-management/manage-api-traffic/add-subscription.png) diff --git a/en/docs/api-management/rename-api-display-name.md b/en/developer-docs/docs/api-management/rename-api-display-name.md similarity index 100% rename from en/docs/api-management/rename-api-display-name.md rename to en/developer-docs/docs/api-management/rename-api-display-name.md diff --git a/en/docs/assets/css/blue-palette-alt2.css b/en/developer-docs/docs/assets/css/blue-palette-alt2.css similarity index 100% rename from en/docs/assets/css/blue-palette-alt2.css rename to en/developer-docs/docs/assets/css/blue-palette-alt2.css diff --git a/en/docs/assets/css/choreotheme.css b/en/developer-docs/docs/assets/css/choreotheme.css similarity index 100% rename from en/docs/assets/css/choreotheme.css rename to en/developer-docs/docs/assets/css/choreotheme.css diff --git a/en/docs/assets/css/config-catalog.css b/en/developer-docs/docs/assets/css/config-catalog.css similarity index 100% rename from en/docs/assets/css/config-catalog.css rename to en/developer-docs/docs/assets/css/config-catalog.css diff --git a/en/docs/assets/css/prism.css b/en/developer-docs/docs/assets/css/prism.css similarity index 100% rename from en/docs/assets/css/prism.css rename to en/developer-docs/docs/assets/css/prism.css diff --git a/en/docs/assets/css/style.css b/en/developer-docs/docs/assets/css/style.css similarity index 100% rename from en/docs/assets/css/style.css rename to en/developer-docs/docs/assets/css/style.css diff --git a/en/docs/assets/css/theme.css b/en/developer-docs/docs/assets/css/theme.css similarity index 100% rename from en/docs/assets/css/theme.css rename to en/developer-docs/docs/assets/css/theme.css diff --git a/en/docs/assets/img/administer/access-control-to-console.png b/en/developer-docs/docs/assets/img/administer/access-control-to-console.png similarity index 100% rename from en/docs/assets/img/administer/access-control-to-console.png rename to en/developer-docs/docs/assets/img/administer/access-control-to-console.png diff --git a/en/docs/assets/img/administer/add-project-level-rules.png b/en/developer-docs/docs/assets/img/administer/add-project-level-rules.png similarity index 100% rename from en/docs/assets/img/administer/add-project-level-rules.png rename to en/developer-docs/docs/assets/img/administer/add-project-level-rules.png diff --git a/en/docs/assets/img/administer/api-with-custom-url.png b/en/developer-docs/docs/assets/img/administer/api-with-custom-url.png similarity index 100% rename from en/docs/assets/img/administer/api-with-custom-url.png rename to en/developer-docs/docs/assets/img/administer/api-with-custom-url.png diff --git a/en/docs/assets/img/administer/configure-an-organization-level-egress-policy.png b/en/developer-docs/docs/assets/img/administer/configure-an-organization-level-egress-policy.png similarity index 100% rename from en/docs/assets/img/administer/configure-an-organization-level-egress-policy.png rename to en/developer-docs/docs/assets/img/administer/configure-an-organization-level-egress-policy.png diff --git a/en/docs/assets/img/administer/configure-domain/active-deployments.png b/en/developer-docs/docs/assets/img/administer/configure-domain/active-deployments.png similarity index 100% rename from en/docs/assets/img/administer/configure-domain/active-deployments.png rename to en/developer-docs/docs/assets/img/administer/configure-domain/active-deployments.png diff --git a/en/docs/assets/img/administer/configure-domain/active-domains.png b/en/developer-docs/docs/assets/img/administer/configure-domain/active-domains.png similarity index 100% rename from en/docs/assets/img/administer/configure-domain/active-domains.png rename to en/developer-docs/docs/assets/img/administer/configure-domain/active-domains.png diff --git a/en/docs/assets/img/administer/configure-domain/cname-target-value.png b/en/developer-docs/docs/assets/img/administer/configure-domain/cname-target-value.png similarity index 100% rename from en/docs/assets/img/administer/configure-domain/cname-target-value.png rename to en/developer-docs/docs/assets/img/administer/configure-domain/cname-target-value.png diff --git a/en/docs/assets/img/administer/configure-domain/custom-url.png b/en/developer-docs/docs/assets/img/administer/configure-domain/custom-url.png similarity index 100% rename from en/docs/assets/img/administer/configure-domain/custom-url.png rename to en/developer-docs/docs/assets/img/administer/configure-domain/custom-url.png diff --git a/en/docs/assets/img/administer/configure-domain/developer-portal-cname-target-value.png b/en/developer-docs/docs/assets/img/administer/configure-domain/developer-portal-cname-target-value.png similarity index 100% rename from en/docs/assets/img/administer/configure-domain/developer-portal-cname-target-value.png rename to en/developer-docs/docs/assets/img/administer/configure-domain/developer-portal-cname-target-value.png diff --git a/en/docs/assets/img/administer/configure-domain/pending-custom-url-request.png b/en/developer-docs/docs/assets/img/administer/configure-domain/pending-custom-url-request.png similarity index 100% rename from en/docs/assets/img/administer/configure-domain/pending-custom-url-request.png rename to en/developer-docs/docs/assets/img/administer/configure-domain/pending-custom-url-request.png diff --git a/en/docs/assets/img/administer/configure-domain/pending-url-requests.png b/en/developer-docs/docs/assets/img/administer/configure-domain/pending-url-requests.png similarity index 66% rename from en/docs/assets/img/administer/configure-domain/pending-url-requests.png rename to en/developer-docs/docs/assets/img/administer/configure-domain/pending-url-requests.png index 625ceeb60..bdd146c20 100644 Binary files a/en/docs/assets/img/administer/configure-domain/pending-url-requests.png and b/en/developer-docs/docs/assets/img/administer/configure-domain/pending-url-requests.png differ diff --git a/en/developer-docs/docs/assets/img/administer/configure-domain/upload-certificate-chain.png b/en/developer-docs/docs/assets/img/administer/configure-domain/upload-certificate-chain.png new file mode 100644 index 000000000..908520284 Binary files /dev/null and b/en/developer-docs/docs/assets/img/administer/configure-domain/upload-certificate-chain.png differ diff --git a/en/docs/assets/img/administer/configure-domain/url-settings.png b/en/developer-docs/docs/assets/img/administer/configure-domain/url-settings.png similarity index 100% rename from en/docs/assets/img/administer/configure-domain/url-settings.png rename to en/developer-docs/docs/assets/img/administer/configure-domain/url-settings.png diff --git a/en/docs/assets/img/administer/create-choreo-organization.png b/en/developer-docs/docs/assets/img/administer/create-choreo-organization.png similarity index 100% rename from en/docs/assets/img/administer/create-choreo-organization.png rename to en/developer-docs/docs/assets/img/administer/create-choreo-organization.png diff --git a/en/docs/assets/img/administer/create-custom-domain.png b/en/developer-docs/docs/assets/img/administer/create-custom-domain.png similarity index 100% rename from en/docs/assets/img/administer/create-custom-domain.png rename to en/developer-docs/docs/assets/img/administer/create-custom-domain.png diff --git a/en/developer-docs/docs/assets/img/administer/create-subscription-plan.png b/en/developer-docs/docs/assets/img/administer/create-subscription-plan.png new file mode 100644 index 000000000..f6189d028 Binary files /dev/null and b/en/developer-docs/docs/assets/img/administer/create-subscription-plan.png differ diff --git a/en/docs/assets/img/administer/devportal-theme/access-devportal-theme.png b/en/developer-docs/docs/assets/img/administer/devportal-theme/access-devportal-theme.png similarity index 100% rename from en/docs/assets/img/administer/devportal-theme/access-devportal-theme.png rename to en/developer-docs/docs/assets/img/administer/devportal-theme/access-devportal-theme.png diff --git a/en/docs/assets/img/administer/devportal-theme/preview-of-customization.png b/en/developer-docs/docs/assets/img/administer/devportal-theme/preview-of-customization.png similarity index 100% rename from en/docs/assets/img/administer/devportal-theme/preview-of-customization.png rename to en/developer-docs/docs/assets/img/administer/devportal-theme/preview-of-customization.png diff --git a/en/docs/assets/img/administer/devportal-theme/publish-or-discard-developer-portal-changes.png b/en/developer-docs/docs/assets/img/administer/devportal-theme/publish-or-discard-developer-portal-changes.png similarity index 100% rename from en/docs/assets/img/administer/devportal-theme/publish-or-discard-developer-portal-changes.png rename to en/developer-docs/docs/assets/img/administer/devportal-theme/publish-or-discard-developer-portal-changes.png diff --git a/en/docs/assets/img/administer/enterprise-login/group-mapping.png b/en/developer-docs/docs/assets/img/administer/enterprise-login/group-mapping.png similarity index 100% rename from en/docs/assets/img/administer/enterprise-login/group-mapping.png rename to en/developer-docs/docs/assets/img/administer/enterprise-login/group-mapping.png diff --git a/en/docs/assets/img/administer/enterprise-login/role-mapping.png b/en/developer-docs/docs/assets/img/administer/enterprise-login/role-mapping.png similarity index 100% rename from en/docs/assets/img/administer/enterprise-login/role-mapping.png rename to en/developer-docs/docs/assets/img/administer/enterprise-login/role-mapping.png diff --git a/en/docs/assets/img/administer/list-custom-domain.png b/en/developer-docs/docs/assets/img/administer/list-custom-domain.png similarity index 100% rename from en/docs/assets/img/administer/list-custom-domain.png rename to en/developer-docs/docs/assets/img/administer/list-custom-domain.png diff --git a/en/docs/assets/img/administer/mapping-level.png b/en/developer-docs/docs/assets/img/administer/mapping-level.png similarity index 100% rename from en/docs/assets/img/administer/mapping-level.png rename to en/developer-docs/docs/assets/img/administer/mapping-level.png diff --git a/en/docs/assets/img/administer/organizations.png b/en/developer-docs/docs/assets/img/administer/organizations.png similarity index 100% rename from en/docs/assets/img/administer/organizations.png rename to en/developer-docs/docs/assets/img/administer/organizations.png diff --git a/en/docs/assets/img/administer/self-sign-up/add-sign-in-method.png b/en/developer-docs/docs/assets/img/administer/self-sign-up/add-sign-in-method.png similarity index 100% rename from en/docs/assets/img/administer/self-sign-up/add-sign-in-method.png rename to en/developer-docs/docs/assets/img/administer/self-sign-up/add-sign-in-method.png diff --git a/en/docs/assets/img/administer/self-sign-up/application.png b/en/developer-docs/docs/assets/img/administer/self-sign-up/application.png similarity index 100% rename from en/docs/assets/img/administer/self-sign-up/application.png rename to en/developer-docs/docs/assets/img/administer/self-sign-up/application.png diff --git a/en/docs/assets/img/administer/self-sign-up/approval-pending.png b/en/developer-docs/docs/assets/img/administer/self-sign-up/approval-pending.png similarity index 100% rename from en/docs/assets/img/administer/self-sign-up/approval-pending.png rename to en/developer-docs/docs/assets/img/administer/self-sign-up/approval-pending.png diff --git a/en/docs/assets/img/administer/self-sign-up/configure-self-registration.png b/en/developer-docs/docs/assets/img/administer/self-sign-up/configure-self-registration.png similarity index 100% rename from en/docs/assets/img/administer/self-sign-up/configure-self-registration.png rename to en/developer-docs/docs/assets/img/administer/self-sign-up/configure-self-registration.png diff --git a/en/docs/assets/img/administer/self-sign-up/copy-handle.png b/en/developer-docs/docs/assets/img/administer/self-sign-up/copy-handle.png similarity index 100% rename from en/docs/assets/img/administer/self-sign-up/copy-handle.png rename to en/developer-docs/docs/assets/img/administer/self-sign-up/copy-handle.png diff --git a/en/docs/assets/img/administer/self-sign-up/create-an-account.png b/en/developer-docs/docs/assets/img/administer/self-sign-up/create-an-account.png similarity index 100% rename from en/docs/assets/img/administer/self-sign-up/create-an-account.png rename to en/developer-docs/docs/assets/img/administer/self-sign-up/create-an-account.png diff --git a/en/docs/assets/img/administer/self-sign-up/create-new-organization.png b/en/developer-docs/docs/assets/img/administer/self-sign-up/create-new-organization.png similarity index 100% rename from en/docs/assets/img/administer/self-sign-up/create-new-organization.png rename to en/developer-docs/docs/assets/img/administer/self-sign-up/create-new-organization.png diff --git a/en/docs/assets/img/administer/self-sign-up/create-organization.png b/en/developer-docs/docs/assets/img/administer/self-sign-up/create-organization.png similarity index 100% rename from en/docs/assets/img/administer/self-sign-up/create-organization.png rename to en/developer-docs/docs/assets/img/administer/self-sign-up/create-organization.png diff --git a/en/docs/assets/img/administer/self-sign-up/email-attribute.png b/en/developer-docs/docs/assets/img/administer/self-sign-up/email-attribute.png similarity index 100% rename from en/docs/assets/img/administer/self-sign-up/email-attribute.png rename to en/developer-docs/docs/assets/img/administer/self-sign-up/email-attribute.png diff --git a/en/docs/assets/img/administer/self-sign-up/profile-attribute.png b/en/developer-docs/docs/assets/img/administer/self-sign-up/profile-attribute.png similarity index 100% rename from en/docs/assets/img/administer/self-sign-up/profile-attribute.png rename to en/developer-docs/docs/assets/img/administer/self-sign-up/profile-attribute.png diff --git a/en/docs/assets/img/administer/self-sign-up/save-attributes-as-scopes.png b/en/developer-docs/docs/assets/img/administer/self-sign-up/save-attributes-as-scopes.png similarity index 100% rename from en/docs/assets/img/administer/self-sign-up/save-attributes-as-scopes.png rename to en/developer-docs/docs/assets/img/administer/self-sign-up/save-attributes-as-scopes.png diff --git a/en/docs/assets/img/administer/self-sign-up/sign-up.png b/en/developer-docs/docs/assets/img/administer/self-sign-up/sign-up.png similarity index 100% rename from en/docs/assets/img/administer/self-sign-up/sign-up.png rename to en/developer-docs/docs/assets/img/administer/self-sign-up/sign-up.png diff --git a/en/docs/assets/img/administer/self-sign-up/user-attributes.png b/en/developer-docs/docs/assets/img/administer/self-sign-up/user-attributes.png similarity index 100% rename from en/docs/assets/img/administer/self-sign-up/user-attributes.png rename to en/developer-docs/docs/assets/img/administer/self-sign-up/user-attributes.png diff --git a/en/docs/assets/img/administer/self-sign-up/view-all-applications.png b/en/developer-docs/docs/assets/img/administer/self-sign-up/view-all-applications.png similarity index 100% rename from en/docs/assets/img/administer/self-sign-up/view-all-applications.png rename to en/developer-docs/docs/assets/img/administer/self-sign-up/view-all-applications.png diff --git a/en/docs/assets/img/api-management/api-discovery.png b/en/developer-docs/docs/assets/img/api-management/api-discovery.png similarity index 100% rename from en/docs/assets/img/api-management/api-discovery.png rename to en/developer-docs/docs/assets/img/api-management/api-discovery.png diff --git a/en/docs/assets/img/api-management/api-policies/add-header.png b/en/developer-docs/docs/assets/img/api-management/api-policies/add-header.png similarity index 100% rename from en/docs/assets/img/api-management/api-policies/add-header.png rename to en/developer-docs/docs/assets/img/api-management/api-policies/add-header.png diff --git a/en/docs/assets/img/api-management/api-policies/add-policy.png b/en/developer-docs/docs/assets/img/api-management/api-policies/add-policy.png similarity index 100% rename from en/docs/assets/img/api-management/api-policies/add-policy.png rename to en/developer-docs/docs/assets/img/api-management/api-policies/add-policy.png diff --git a/en/docs/assets/img/api-management/api-policies/added-policy.png b/en/developer-docs/docs/assets/img/api-management/api-policies/added-policy.png similarity index 100% rename from en/docs/assets/img/api-management/api-policies/added-policy.png rename to en/developer-docs/docs/assets/img/api-management/api-policies/added-policy.png diff --git a/en/docs/assets/img/api-management/api-policies/advanced-settings/detailed-access-log-setting.png b/en/developer-docs/docs/assets/img/api-management/api-policies/advanced-settings/detailed-access-log-setting.png similarity index 100% rename from en/docs/assets/img/api-management/api-policies/advanced-settings/detailed-access-log-setting.png rename to en/developer-docs/docs/assets/img/api-management/api-policies/advanced-settings/detailed-access-log-setting.png diff --git a/en/docs/assets/img/api-management/api-policies/advanced-settings/hostname-verification-setting.png b/en/developer-docs/docs/assets/img/api-management/api-policies/advanced-settings/hostname-verification-setting.png similarity index 100% rename from en/docs/assets/img/api-management/api-policies/advanced-settings/hostname-verification-setting.png rename to en/developer-docs/docs/assets/img/api-management/api-policies/advanced-settings/hostname-verification-setting.png diff --git a/en/docs/assets/img/api-management/api-policies/advanced-settings/http-version-setting.png b/en/developer-docs/docs/assets/img/api-management/api-policies/advanced-settings/http-version-setting.png similarity index 100% rename from en/docs/assets/img/api-management/api-policies/advanced-settings/http-version-setting.png rename to en/developer-docs/docs/assets/img/api-management/api-policies/advanced-settings/http-version-setting.png diff --git a/en/docs/assets/img/api-management/api-policies/advanced-settings/minimum-evictable-idle-time-setting.png b/en/developer-docs/docs/assets/img/api-management/api-policies/advanced-settings/minimum-evictable-idle-time-setting.png similarity index 100% rename from en/docs/assets/img/api-management/api-policies/advanced-settings/minimum-evictable-idle-time-setting.png rename to en/developer-docs/docs/assets/img/api-management/api-policies/advanced-settings/minimum-evictable-idle-time-setting.png diff --git a/en/docs/assets/img/api-management/api-policies/attach-policy.png b/en/developer-docs/docs/assets/img/api-management/api-policies/attach-policy.png similarity index 100% rename from en/docs/assets/img/api-management/api-policies/attach-policy.png rename to en/developer-docs/docs/assets/img/api-management/api-policies/attach-policy.png diff --git a/en/docs/assets/img/api-management/api-policies/ballerina-project.png b/en/developer-docs/docs/assets/img/api-management/api-policies/ballerina-project.png similarity index 100% rename from en/docs/assets/img/api-management/api-policies/ballerina-project.png rename to en/developer-docs/docs/assets/img/api-management/api-policies/ballerina-project.png diff --git a/en/docs/assets/img/api-management/api-policies/ballerina-toml.png b/en/developer-docs/docs/assets/img/api-management/api-policies/ballerina-toml.png similarity index 100% rename from en/docs/assets/img/api-management/api-policies/ballerina-toml.png rename to en/developer-docs/docs/assets/img/api-management/api-policies/ballerina-toml.png diff --git a/en/docs/assets/img/api-management/api-policies/configurable-values.png b/en/developer-docs/docs/assets/img/api-management/api-policies/configurable-values.png similarity index 100% rename from en/docs/assets/img/api-management/api-policies/configurable-values.png rename to en/developer-docs/docs/assets/img/api-management/api-policies/configurable-values.png diff --git a/en/docs/assets/img/api-management/api-policies/configure-add-header.png b/en/developer-docs/docs/assets/img/api-management/api-policies/configure-add-header.png similarity index 100% rename from en/docs/assets/img/api-management/api-policies/configure-add-header.png rename to en/developer-docs/docs/assets/img/api-management/api-policies/configure-add-header.png diff --git a/en/docs/assets/img/api-management/api-policies/configure-parameters.png b/en/developer-docs/docs/assets/img/api-management/api-policies/configure-parameters.png similarity index 100% rename from en/docs/assets/img/api-management/api-policies/configure-parameters.png rename to en/developer-docs/docs/assets/img/api-management/api-policies/configure-parameters.png diff --git a/en/docs/assets/img/api-management/api-policies/published-policy.png b/en/developer-docs/docs/assets/img/api-management/api-policies/published-policy.png similarity index 100% rename from en/docs/assets/img/api-management/api-policies/published-policy.png rename to en/developer-docs/docs/assets/img/api-management/api-policies/published-policy.png diff --git a/en/docs/assets/img/api-management/api-policies/request-response-flow.png b/en/developer-docs/docs/assets/img/api-management/api-policies/request-response-flow.png similarity index 100% rename from en/docs/assets/img/api-management/api-policies/request-response-flow.png rename to en/developer-docs/docs/assets/img/api-management/api-policies/request-response-flow.png diff --git a/en/docs/assets/img/api-management/api-policies/save-and-deploy.png b/en/developer-docs/docs/assets/img/api-management/api-policies/save-and-deploy.png similarity index 100% rename from en/docs/assets/img/api-management/api-policies/save-and-deploy.png rename to en/developer-docs/docs/assets/img/api-management/api-policies/save-and-deploy.png diff --git a/en/docs/assets/img/api-management/api-policies/select-policy.png b/en/developer-docs/docs/assets/img/api-management/api-policies/select-policy.png similarity index 100% rename from en/docs/assets/img/api-management/api-policies/select-policy.png rename to en/developer-docs/docs/assets/img/api-management/api-policies/select-policy.png diff --git a/en/docs/assets/img/api-management/applications.png b/en/developer-docs/docs/assets/img/api-management/applications.png similarity index 100% rename from en/docs/assets/img/api-management/applications.png rename to en/developer-docs/docs/assets/img/api-management/applications.png diff --git a/en/docs/assets/img/api-management/authentication.png b/en/developer-docs/docs/assets/img/api-management/authentication.png similarity index 100% rename from en/docs/assets/img/api-management/authentication.png rename to en/developer-docs/docs/assets/img/api-management/authentication.png diff --git a/en/docs/assets/img/api-management/business-plans.png b/en/developer-docs/docs/assets/img/api-management/business-plans.png similarity index 100% rename from en/docs/assets/img/api-management/business-plans.png rename to en/developer-docs/docs/assets/img/api-management/business-plans.png diff --git a/en/docs/assets/img/api-management/developer-portal-home-page.png b/en/developer-docs/docs/assets/img/api-management/developer-portal-home-page.png similarity index 100% rename from en/docs/assets/img/api-management/developer-portal-home-page.png rename to en/developer-docs/docs/assets/img/api-management/developer-portal-home-page.png diff --git a/en/docs/assets/img/api-management/invoke-api.png b/en/developer-docs/docs/assets/img/api-management/invoke-api.png similarity index 100% rename from en/docs/assets/img/api-management/invoke-api.png rename to en/developer-docs/docs/assets/img/api-management/invoke-api.png diff --git a/en/docs/assets/img/api-management/manage-api-traffic/add-subscription.png b/en/developer-docs/docs/assets/img/api-management/manage-api-traffic/add-subscription.png similarity index 53% rename from en/docs/assets/img/api-management/manage-api-traffic/add-subscription.png rename to en/developer-docs/docs/assets/img/api-management/manage-api-traffic/add-subscription.png index a6e5e84d3..d5a159f97 100644 Binary files a/en/docs/assets/img/api-management/manage-api-traffic/add-subscription.png and b/en/developer-docs/docs/assets/img/api-management/manage-api-traffic/add-subscription.png differ diff --git a/en/developer-docs/docs/assets/img/api-management/manage-api-traffic/enable-toggle.png b/en/developer-docs/docs/assets/img/api-management/manage-api-traffic/enable-toggle.png new file mode 100644 index 000000000..61566d667 Binary files /dev/null and b/en/developer-docs/docs/assets/img/api-management/manage-api-traffic/enable-toggle.png differ diff --git a/en/docs/assets/img/api-management/manage-api-traffic/throttle-response.png b/en/developer-docs/docs/assets/img/api-management/manage-api-traffic/throttle-response.png similarity index 100% rename from en/docs/assets/img/api-management/manage-api-traffic/throttle-response.png rename to en/developer-docs/docs/assets/img/api-management/manage-api-traffic/throttle-response.png diff --git a/en/docs/assets/img/api-management/subscription.png b/en/developer-docs/docs/assets/img/api-management/subscription.png similarity index 100% rename from en/docs/assets/img/api-management/subscription.png rename to en/developer-docs/docs/assets/img/api-management/subscription.png diff --git a/en/docs/assets/img/authentication-and-authorization/associate-certificate.png b/en/developer-docs/docs/assets/img/authentication-and-authorization/associate-certificate.png similarity index 100% rename from en/docs/assets/img/authentication-and-authorization/associate-certificate.png rename to en/developer-docs/docs/assets/img/authentication-and-authorization/associate-certificate.png diff --git a/en/docs/assets/img/authentication-and-authorization/certificate-details.png b/en/developer-docs/docs/assets/img/authentication-and-authorization/certificate-details.png similarity index 100% rename from en/docs/assets/img/authentication-and-authorization/certificate-details.png rename to en/developer-docs/docs/assets/img/authentication-and-authorization/certificate-details.png diff --git a/en/docs/assets/img/authentication-and-authorization/generate-new-key-pair.png b/en/developer-docs/docs/assets/img/authentication-and-authorization/generate-new-key-pair.png similarity index 100% rename from en/docs/assets/img/authentication-and-authorization/generate-new-key-pair.png rename to en/developer-docs/docs/assets/img/authentication-and-authorization/generate-new-key-pair.png diff --git a/en/docs/assets/img/authentication-and-authorization/mutual-ssl-authentication.png b/en/developer-docs/docs/assets/img/authentication-and-authorization/mutual-ssl-authentication.png similarity index 100% rename from en/docs/assets/img/authentication-and-authorization/mutual-ssl-authentication.png rename to en/developer-docs/docs/assets/img/authentication-and-authorization/mutual-ssl-authentication.png diff --git a/en/docs/assets/img/authentication-and-authorization/use-own-key-pair.png b/en/developer-docs/docs/assets/img/authentication-and-authorization/use-own-key-pair.png similarity index 100% rename from en/docs/assets/img/authentication-and-authorization/use-own-key-pair.png rename to en/developer-docs/docs/assets/img/authentication-and-authorization/use-own-key-pair.png diff --git a/en/docs/assets/img/authentication-and-authorization/view-and-download.png b/en/developer-docs/docs/assets/img/authentication-and-authorization/view-and-download.png similarity index 100% rename from en/docs/assets/img/authentication-and-authorization/view-and-download.png rename to en/developer-docs/docs/assets/img/authentication-and-authorization/view-and-download.png diff --git a/en/docs/assets/img/choreo-cli/personal-access-tokens/account-settings.png b/en/developer-docs/docs/assets/img/choreo-cli/personal-access-tokens/account-settings.png similarity index 100% rename from en/docs/assets/img/choreo-cli/personal-access-tokens/account-settings.png rename to en/developer-docs/docs/assets/img/choreo-cli/personal-access-tokens/account-settings.png diff --git a/en/docs/assets/img/choreo-cli/personal-access-tokens/create-a-pat.png b/en/developer-docs/docs/assets/img/choreo-cli/personal-access-tokens/create-a-pat.png similarity index 100% rename from en/docs/assets/img/choreo-cli/personal-access-tokens/create-a-pat.png rename to en/developer-docs/docs/assets/img/choreo-cli/personal-access-tokens/create-a-pat.png diff --git a/en/docs/assets/img/choreo-cli/personal-access-tokens/generated-pat.png b/en/developer-docs/docs/assets/img/choreo-cli/personal-access-tokens/generated-pat.png similarity index 100% rename from en/docs/assets/img/choreo-cli/personal-access-tokens/generated-pat.png rename to en/developer-docs/docs/assets/img/choreo-cli/personal-access-tokens/generated-pat.png diff --git a/en/docs/assets/img/choreo-cli/personal-access-tokens/pat-listing.png b/en/developer-docs/docs/assets/img/choreo-cli/personal-access-tokens/pat-listing.png similarity index 100% rename from en/docs/assets/img/choreo-cli/personal-access-tokens/pat-listing.png rename to en/developer-docs/docs/assets/img/choreo-cli/personal-access-tokens/pat-listing.png diff --git a/en/docs/assets/img/choreo-cli/personal-access-tokens/profile.png b/en/developer-docs/docs/assets/img/choreo-cli/personal-access-tokens/profile.png similarity index 100% rename from en/docs/assets/img/choreo-cli/personal-access-tokens/profile.png rename to en/developer-docs/docs/assets/img/choreo-cli/personal-access-tokens/profile.png diff --git a/en/docs/assets/img/choreo-concepts/choreo-environments.png b/en/developer-docs/docs/assets/img/choreo-concepts/choreo-environments.png similarity index 100% rename from en/docs/assets/img/choreo-concepts/choreo-environments.png rename to en/developer-docs/docs/assets/img/choreo-concepts/choreo-environments.png diff --git a/en/docs/assets/img/choreo-concepts/deployment-tracks-api-versioning.md.png b/en/developer-docs/docs/assets/img/choreo-concepts/deployment-tracks-api-versioning.md.png similarity index 100% rename from en/docs/assets/img/choreo-concepts/deployment-tracks-api-versioning.md.png rename to en/developer-docs/docs/assets/img/choreo-concepts/deployment-tracks-api-versioning.md.png diff --git a/en/docs/assets/img/choreo-concepts/deployment-tracks-container-registry.png b/en/developer-docs/docs/assets/img/choreo-concepts/deployment-tracks-container-registry.png similarity index 100% rename from en/docs/assets/img/choreo-concepts/deployment-tracks-container-registry.png rename to en/developer-docs/docs/assets/img/choreo-concepts/deployment-tracks-container-registry.png diff --git a/en/docs/assets/img/choreo-concepts/deployment-tracks-source-repo.png b/en/developer-docs/docs/assets/img/choreo-concepts/deployment-tracks-source-repo.png similarity index 100% rename from en/docs/assets/img/choreo-concepts/deployment-tracks-source-repo.png rename to en/developer-docs/docs/assets/img/choreo-concepts/deployment-tracks-source-repo.png diff --git a/en/docs/assets/img/choreo-concepts/environments-and-dataplanes.png b/en/developer-docs/docs/assets/img/choreo-concepts/environments-and-dataplanes.png similarity index 100% rename from en/docs/assets/img/choreo-concepts/environments-and-dataplanes.png rename to en/developer-docs/docs/assets/img/choreo-concepts/environments-and-dataplanes.png diff --git a/en/docs/assets/img/choreo-concepts/high-level-view.png b/en/developer-docs/docs/assets/img/choreo-concepts/high-level-view.png similarity index 100% rename from en/docs/assets/img/choreo-concepts/high-level-view.png rename to en/developer-docs/docs/assets/img/choreo-concepts/high-level-view.png diff --git a/en/docs/assets/img/choreo-concepts/marketplace/internal-marketplace.png b/en/developer-docs/docs/assets/img/choreo-concepts/marketplace/internal-marketplace.png similarity index 100% rename from en/docs/assets/img/choreo-concepts/marketplace/internal-marketplace.png rename to en/developer-docs/docs/assets/img/choreo-concepts/marketplace/internal-marketplace.png diff --git a/en/docs/assets/img/choreo-concepts/observability-architecture.png b/en/developer-docs/docs/assets/img/choreo-concepts/observability-architecture.png similarity index 100% rename from en/docs/assets/img/choreo-concepts/observability-architecture.png rename to en/developer-docs/docs/assets/img/choreo-concepts/observability-architecture.png diff --git a/en/docs/assets/img/choreo-concepts/private-data-plane-architecture.png b/en/developer-docs/docs/assets/img/choreo-concepts/private-data-plane-architecture.png similarity index 100% rename from en/docs/assets/img/choreo-concepts/private-data-plane-architecture.png rename to en/developer-docs/docs/assets/img/choreo-concepts/private-data-plane-architecture.png diff --git a/en/docs/assets/img/choreo-concepts/project.png b/en/developer-docs/docs/assets/img/choreo-concepts/project.png similarity index 100% rename from en/docs/assets/img/choreo-concepts/project.png rename to en/developer-docs/docs/assets/img/choreo-concepts/project.png diff --git a/en/docs/assets/img/choreo-concepts/resource-hierarchy.png b/en/developer-docs/docs/assets/img/choreo-concepts/resource-hierarchy.png similarity index 100% rename from en/docs/assets/img/choreo-concepts/resource-hierarchy.png rename to en/developer-docs/docs/assets/img/choreo-concepts/resource-hierarchy.png diff --git a/en/docs/assets/img/choreo-concepts/saas-data-plane-architecture.png b/en/developer-docs/docs/assets/img/choreo-concepts/saas-data-plane-architecture.png similarity index 100% rename from en/docs/assets/img/choreo-concepts/saas-data-plane-architecture.png rename to en/developer-docs/docs/assets/img/choreo-concepts/saas-data-plane-architecture.png diff --git a/en/docs/assets/img/choreo-logo.png b/en/developer-docs/docs/assets/img/choreo-logo.png similarity index 100% rename from en/docs/assets/img/choreo-logo.png rename to en/developer-docs/docs/assets/img/choreo-logo.png diff --git a/en/docs/assets/img/consume/add-apis.png b/en/developer-docs/docs/assets/img/consume/add-apis.png similarity index 100% rename from en/docs/assets/img/consume/add-apis.png rename to en/developer-docs/docs/assets/img/consume/add-apis.png diff --git a/en/docs/assets/img/consume/api-overview.png b/en/developer-docs/docs/assets/img/consume/api-overview.png similarity index 100% rename from en/docs/assets/img/consume/api-overview.png rename to en/developer-docs/docs/assets/img/consume/api-overview.png diff --git a/en/docs/assets/img/consume/developer-portal-apis.png b/en/developer-docs/docs/assets/img/consume/developer-portal-apis.png similarity index 100% rename from en/docs/assets/img/consume/developer-portal-apis.png rename to en/developer-docs/docs/assets/img/consume/developer-portal-apis.png diff --git a/en/developer-docs/docs/assets/img/cost-optimization/ComponentLevel.png b/en/developer-docs/docs/assets/img/cost-optimization/ComponentLevel.png new file mode 100644 index 000000000..029a67f9f Binary files /dev/null and b/en/developer-docs/docs/assets/img/cost-optimization/ComponentLevel.png differ diff --git a/en/developer-docs/docs/assets/img/cost-optimization/OrganizationLevel.png b/en/developer-docs/docs/assets/img/cost-optimization/OrganizationLevel.png new file mode 100644 index 000000000..620550040 Binary files /dev/null and b/en/developer-docs/docs/assets/img/cost-optimization/OrganizationLevel.png differ diff --git a/en/developer-docs/docs/assets/img/cost-optimization/ProjectLevel.png b/en/developer-docs/docs/assets/img/cost-optimization/ProjectLevel.png new file mode 100644 index 000000000..4930de1dd Binary files /dev/null and b/en/developer-docs/docs/assets/img/cost-optimization/ProjectLevel.png differ diff --git a/en/developer-docs/docs/assets/img/cost-optimization/annual_savings.png b/en/developer-docs/docs/assets/img/cost-optimization/annual_savings.png new file mode 100644 index 000000000..0316fd150 Binary files /dev/null and b/en/developer-docs/docs/assets/img/cost-optimization/annual_savings.png differ diff --git a/en/developer-docs/docs/assets/img/cost-optimization/component_details.png b/en/developer-docs/docs/assets/img/cost-optimization/component_details.png new file mode 100644 index 000000000..107be7bf4 Binary files /dev/null and b/en/developer-docs/docs/assets/img/cost-optimization/component_details.png differ diff --git a/en/developer-docs/docs/assets/img/cost-optimization/component_metrics_cards.png b/en/developer-docs/docs/assets/img/cost-optimization/component_metrics_cards.png new file mode 100644 index 000000000..74401bbe8 Binary files /dev/null and b/en/developer-docs/docs/assets/img/cost-optimization/component_metrics_cards.png differ diff --git a/en/developer-docs/docs/assets/img/cost-optimization/component_summary.png b/en/developer-docs/docs/assets/img/cost-optimization/component_summary.png new file mode 100644 index 000000000..4bf959dc1 Binary files /dev/null and b/en/developer-docs/docs/assets/img/cost-optimization/component_summary.png differ diff --git a/en/developer-docs/docs/assets/img/cost-optimization/cost_analysis.png b/en/developer-docs/docs/assets/img/cost-optimization/cost_analysis.png new file mode 100644 index 000000000..d86cc6357 Binary files /dev/null and b/en/developer-docs/docs/assets/img/cost-optimization/cost_analysis.png differ diff --git a/en/developer-docs/docs/assets/img/cost-optimization/cpu_metrics.png b/en/developer-docs/docs/assets/img/cost-optimization/cpu_metrics.png new file mode 100644 index 000000000..bb0bfc6f8 Binary files /dev/null and b/en/developer-docs/docs/assets/img/cost-optimization/cpu_metrics.png differ diff --git a/en/developer-docs/docs/assets/img/cost-optimization/deployment_summary.png b/en/developer-docs/docs/assets/img/cost-optimization/deployment_summary.png new file mode 100644 index 000000000..08f2a564a Binary files /dev/null and b/en/developer-docs/docs/assets/img/cost-optimization/deployment_summary.png differ diff --git a/en/developer-docs/docs/assets/img/cost-optimization/estimated_monthly_cost.png b/en/developer-docs/docs/assets/img/cost-optimization/estimated_monthly_cost.png new file mode 100644 index 000000000..ab5a5cd5b Binary files /dev/null and b/en/developer-docs/docs/assets/img/cost-optimization/estimated_monthly_cost.png differ diff --git a/en/developer-docs/docs/assets/img/cost-optimization/memory_metrics.png b/en/developer-docs/docs/assets/img/cost-optimization/memory_metrics.png new file mode 100644 index 000000000..a11f36305 Binary files /dev/null and b/en/developer-docs/docs/assets/img/cost-optimization/memory_metrics.png differ diff --git a/en/developer-docs/docs/assets/img/cost-optimization/monthly_cost.png b/en/developer-docs/docs/assets/img/cost-optimization/monthly_cost.png new file mode 100644 index 000000000..be59b09f6 Binary files /dev/null and b/en/developer-docs/docs/assets/img/cost-optimization/monthly_cost.png differ diff --git a/en/developer-docs/docs/assets/img/cost-optimization/monthly_missed_savings.png b/en/developer-docs/docs/assets/img/cost-optimization/monthly_missed_savings.png new file mode 100644 index 000000000..0b7785963 Binary files /dev/null and b/en/developer-docs/docs/assets/img/cost-optimization/monthly_missed_savings.png differ diff --git a/en/developer-docs/docs/assets/img/cost-optimization/monthly_savings_summary.png b/en/developer-docs/docs/assets/img/cost-optimization/monthly_savings_summary.png new file mode 100644 index 000000000..caa1b259f Binary files /dev/null and b/en/developer-docs/docs/assets/img/cost-optimization/monthly_savings_summary.png differ diff --git a/en/developer-docs/docs/assets/img/cost-optimization/project_summary.png b/en/developer-docs/docs/assets/img/cost-optimization/project_summary.png new file mode 100644 index 000000000..24ca956b6 Binary files /dev/null and b/en/developer-docs/docs/assets/img/cost-optimization/project_summary.png differ diff --git a/en/developer-docs/docs/assets/img/cost-optimization/recommendations.png b/en/developer-docs/docs/assets/img/cost-optimization/recommendations.png new file mode 100644 index 000000000..4aa2d73bd Binary files /dev/null and b/en/developer-docs/docs/assets/img/cost-optimization/recommendations.png differ diff --git a/en/developer-docs/docs/assets/img/cost-optimization/release_selection.png b/en/developer-docs/docs/assets/img/cost-optimization/release_selection.png new file mode 100644 index 000000000..039675b0c Binary files /dev/null and b/en/developer-docs/docs/assets/img/cost-optimization/release_selection.png differ diff --git a/en/developer-docs/docs/assets/img/cost-optimization/resource_efficiency.png b/en/developer-docs/docs/assets/img/cost-optimization/resource_efficiency.png new file mode 100644 index 000000000..463f1021d Binary files /dev/null and b/en/developer-docs/docs/assets/img/cost-optimization/resource_efficiency.png differ diff --git a/en/developer-docs/docs/assets/img/cost-optimization/total_monthly_savings.png b/en/developer-docs/docs/assets/img/cost-optimization/total_monthly_savings.png new file mode 100644 index 000000000..1de1c63d8 Binary files /dev/null and b/en/developer-docs/docs/assets/img/cost-optimization/total_monthly_savings.png differ diff --git a/en/docs/assets/img/develop-components/deploy/authz-choreo-github-app.png b/en/developer-docs/docs/assets/img/develop-components/deploy/authz-choreo-github-app.png similarity index 100% rename from en/docs/assets/img/develop-components/deploy/authz-choreo-github-app.png rename to en/developer-docs/docs/assets/img/develop-components/deploy/authz-choreo-github-app.png diff --git a/en/docs/assets/img/develop-components/deploy/build-deploy-page-logs.png b/en/developer-docs/docs/assets/img/develop-components/deploy/build-deploy-page-logs.png similarity index 100% rename from en/docs/assets/img/develop-components/deploy/build-deploy-page-logs.png rename to en/developer-docs/docs/assets/img/develop-components/deploy/build-deploy-page-logs.png diff --git a/en/docs/assets/img/develop-components/deploy/build-deploy-page.png b/en/developer-docs/docs/assets/img/develop-components/deploy/build-deploy-page.png similarity index 100% rename from en/docs/assets/img/develop-components/deploy/build-deploy-page.png rename to en/developer-docs/docs/assets/img/develop-components/deploy/build-deploy-page.png diff --git a/en/docs/assets/img/develop-components/deploy/create-component-authz-github-page.png b/en/developer-docs/docs/assets/img/develop-components/deploy/create-component-authz-github-page.png similarity index 100% rename from en/docs/assets/img/develop-components/deploy/create-component-authz-github-page.png rename to en/developer-docs/docs/assets/img/develop-components/deploy/create-component-authz-github-page.png diff --git a/en/docs/assets/img/develop-components/deploy/create-component-connected-repo.png b/en/developer-docs/docs/assets/img/develop-components/deploy/create-component-connected-repo.png similarity index 100% rename from en/docs/assets/img/develop-components/deploy/create-component-connected-repo.png rename to en/developer-docs/docs/assets/img/develop-components/deploy/create-component-connected-repo.png diff --git a/en/docs/assets/img/develop-components/deploy/deploy-app-config-file-mount.png b/en/developer-docs/docs/assets/img/develop-components/deploy/deploy-app-config-file-mount.png similarity index 100% rename from en/docs/assets/img/develop-components/deploy/deploy-app-config-file-mount.png rename to en/developer-docs/docs/assets/img/develop-components/deploy/deploy-app-config-file-mount.png diff --git a/en/docs/assets/img/develop-components/deploy/deploy-app-config-page.png b/en/developer-docs/docs/assets/img/develop-components/deploy/deploy-app-config-page.png similarity index 100% rename from en/docs/assets/img/develop-components/deploy/deploy-app-config-page.png rename to en/developer-docs/docs/assets/img/develop-components/deploy/deploy-app-config-page.png diff --git a/en/docs/assets/img/develop-components/deploy/deploy-app-config-type-mount-page.png b/en/developer-docs/docs/assets/img/develop-components/deploy/deploy-app-config-type-mount-page.png similarity index 100% rename from en/docs/assets/img/develop-components/deploy/deploy-app-config-type-mount-page.png rename to en/developer-docs/docs/assets/img/develop-components/deploy/deploy-app-config-type-mount-page.png diff --git a/en/docs/assets/img/develop-components/deploy/github-repo-access.png b/en/developer-docs/docs/assets/img/develop-components/deploy/github-repo-access.png similarity index 100% rename from en/docs/assets/img/develop-components/deploy/github-repo-access.png rename to en/developer-docs/docs/assets/img/develop-components/deploy/github-repo-access.png diff --git a/en/docs/assets/img/develop-components/develop-a-rest-api-proxy/rest-api-proxy-response.png b/en/developer-docs/docs/assets/img/develop-components/develop-a-rest-api-proxy/rest-api-proxy-response.png similarity index 100% rename from en/docs/assets/img/develop-components/develop-a-rest-api-proxy/rest-api-proxy-response.png rename to en/developer-docs/docs/assets/img/develop-components/develop-a-rest-api-proxy/rest-api-proxy-response.png diff --git a/en/docs/assets/img/develop-components/develop-a-rest-api-proxy/try-out-response.png b/en/developer-docs/docs/assets/img/develop-components/develop-a-rest-api-proxy/try-out-response.png similarity index 100% rename from en/docs/assets/img/develop-components/develop-a-rest-api-proxy/try-out-response.png rename to en/developer-docs/docs/assets/img/develop-components/develop-a-rest-api-proxy/try-out-response.png diff --git a/en/docs/assets/img/develop-components/develop-a-scheduled-integration/Received-email.png b/en/developer-docs/docs/assets/img/develop-components/develop-a-scheduled-integration/Received-email.png similarity index 100% rename from en/docs/assets/img/develop-components/develop-a-scheduled-integration/Received-email.png rename to en/developer-docs/docs/assets/img/develop-components/develop-a-scheduled-integration/Received-email.png diff --git a/en/docs/assets/img/develop-components/develop-a-scheduled-integration/configurable-variable-as-a-secret.png b/en/developer-docs/docs/assets/img/develop-components/develop-a-scheduled-integration/configurable-variable-as-a-secret.png similarity index 100% rename from en/docs/assets/img/develop-components/develop-a-scheduled-integration/configurable-variable-as-a-secret.png rename to en/developer-docs/docs/assets/img/develop-components/develop-a-scheduled-integration/configurable-variable-as-a-secret.png diff --git a/en/docs/assets/img/develop-components/develop-a-scheduled-integration/execution_history.png b/en/developer-docs/docs/assets/img/develop-components/develop-a-scheduled-integration/execution_history.png similarity index 100% rename from en/docs/assets/img/develop-components/develop-a-scheduled-integration/execution_history.png rename to en/developer-docs/docs/assets/img/develop-components/develop-a-scheduled-integration/execution_history.png diff --git a/en/docs/assets/img/develop-components/develop-a-scheduled-integration/execution_logs.png b/en/developer-docs/docs/assets/img/develop-components/develop-a-scheduled-integration/execution_logs.png similarity index 100% rename from en/docs/assets/img/develop-components/develop-a-scheduled-integration/execution_logs.png rename to en/developer-docs/docs/assets/img/develop-components/develop-a-scheduled-integration/execution_logs.png diff --git a/en/docs/assets/img/develop-components/develop-a-scheduled-integration/total_executions.png b/en/developer-docs/docs/assets/img/develop-components/develop-a-scheduled-integration/total_executions.png similarity index 100% rename from en/docs/assets/img/develop-components/develop-a-scheduled-integration/total_executions.png rename to en/developer-docs/docs/assets/img/develop-components/develop-a-scheduled-integration/total_executions.png diff --git a/en/docs/assets/img/develop-components/develop-a-scheduled-integration/update-secret.png b/en/developer-docs/docs/assets/img/develop-components/develop-a-scheduled-integration/update-secret.png similarity index 100% rename from en/docs/assets/img/develop-components/develop-a-scheduled-integration/update-secret.png rename to en/developer-docs/docs/assets/img/develop-components/develop-a-scheduled-integration/update-secret.png diff --git a/en/docs/assets/img/develop-components/develop-using-vs-code/clone-a-project.gif b/en/developer-docs/docs/assets/img/develop-components/develop-using-vs-code/clone-a-project.gif similarity index 100% rename from en/docs/assets/img/develop-components/develop-using-vs-code/clone-a-project.gif rename to en/developer-docs/docs/assets/img/develop-components/develop-using-vs-code/clone-a-project.gif diff --git a/en/docs/assets/img/develop-components/develop-using-vs-code/component-details-view.png b/en/developer-docs/docs/assets/img/develop-components/develop-using-vs-code/component-details-view.png similarity index 100% rename from en/docs/assets/img/develop-components/develop-using-vs-code/component-details-view.png rename to en/developer-docs/docs/assets/img/develop-components/develop-using-vs-code/component-details-view.png diff --git a/en/docs/assets/img/develop-components/develop-using-vs-code/component-form.png b/en/developer-docs/docs/assets/img/develop-components/develop-using-vs-code/component-form.png similarity index 100% rename from en/docs/assets/img/develop-components/develop-using-vs-code/component-form.png rename to en/developer-docs/docs/assets/img/develop-components/develop-using-vs-code/component-form.png diff --git a/en/docs/assets/img/develop-components/develop-using-vs-code/create-a-component.gif b/en/developer-docs/docs/assets/img/develop-components/develop-using-vs-code/create-a-component.gif similarity index 100% rename from en/docs/assets/img/develop-components/develop-using-vs-code/create-a-component.gif rename to en/developer-docs/docs/assets/img/develop-components/develop-using-vs-code/create-a-component.gif diff --git a/en/docs/assets/img/develop-components/develop-using-vs-code/create-a-project.gif b/en/developer-docs/docs/assets/img/develop-components/develop-using-vs-code/create-a-project.gif similarity index 100% rename from en/docs/assets/img/develop-components/develop-using-vs-code/create-a-project.gif rename to en/developer-docs/docs/assets/img/develop-components/develop-using-vs-code/create-a-project.gif diff --git a/en/docs/assets/img/develop-components/develop-using-vs-code/create-component-btn.png b/en/developer-docs/docs/assets/img/develop-components/develop-using-vs-code/create-component-btn.png similarity index 100% rename from en/docs/assets/img/develop-components/develop-using-vs-code/create-component-btn.png rename to en/developer-docs/docs/assets/img/develop-components/develop-using-vs-code/create-component-btn.png diff --git a/en/docs/assets/img/develop-components/develop-using-vs-code/create-project-tree-view.png b/en/developer-docs/docs/assets/img/develop-components/develop-using-vs-code/create-project-tree-view.png similarity index 100% rename from en/docs/assets/img/develop-components/develop-using-vs-code/create-project-tree-view.png rename to en/developer-docs/docs/assets/img/develop-components/develop-using-vs-code/create-project-tree-view.png diff --git a/en/docs/assets/img/develop-components/develop-using-vs-code/link-dir-btn.png b/en/developer-docs/docs/assets/img/develop-components/develop-using-vs-code/link-dir-btn.png similarity index 100% rename from en/docs/assets/img/develop-components/develop-using-vs-code/link-dir-btn.png rename to en/developer-docs/docs/assets/img/develop-components/develop-using-vs-code/link-dir-btn.png diff --git a/en/docs/assets/img/develop-components/develop-using-vs-code/projects-and-orgs.png b/en/developer-docs/docs/assets/img/develop-components/develop-using-vs-code/projects-and-orgs.png similarity index 100% rename from en/docs/assets/img/develop-components/develop-using-vs-code/projects-and-orgs.png rename to en/developer-docs/docs/assets/img/develop-components/develop-using-vs-code/projects-and-orgs.png diff --git a/en/docs/assets/img/develop-components/develop-using-vs-code/push-changes.gif b/en/developer-docs/docs/assets/img/develop-components/develop-using-vs-code/push-changes.gif similarity index 100% rename from en/docs/assets/img/develop-components/develop-using-vs-code/push-changes.gif rename to en/developer-docs/docs/assets/img/develop-components/develop-using-vs-code/push-changes.gif diff --git a/en/docs/assets/img/develop-components/develop-using-vs-code/sign-in.png b/en/developer-docs/docs/assets/img/develop-components/develop-using-vs-code/sign-in.png similarity index 100% rename from en/docs/assets/img/develop-components/develop-using-vs-code/sign-in.png rename to en/developer-docs/docs/assets/img/develop-components/develop-using-vs-code/sign-in.png diff --git a/en/docs/assets/img/develop-components/micro-integrator/add-server.png b/en/developer-docs/docs/assets/img/develop-components/micro-integrator/add-server.png similarity index 100% rename from en/docs/assets/img/develop-components/micro-integrator/add-server.png rename to en/developer-docs/docs/assets/img/develop-components/micro-integrator/add-server.png diff --git a/en/docs/assets/img/develop-components/micro-integrator/click_change_runtime.png b/en/developer-docs/docs/assets/img/develop-components/micro-integrator/click_change_runtime.png similarity index 100% rename from en/docs/assets/img/develop-components/micro-integrator/click_change_runtime.png rename to en/developer-docs/docs/assets/img/develop-components/micro-integrator/click_change_runtime.png diff --git a/en/docs/assets/img/develop-components/micro-integrator/config_file.png b/en/developer-docs/docs/assets/img/develop-components/micro-integrator/config_file.png similarity index 100% rename from en/docs/assets/img/develop-components/micro-integrator/config_file.png rename to en/developer-docs/docs/assets/img/develop-components/micro-integrator/config_file.png diff --git a/en/docs/assets/img/develop-components/micro-integrator/define-a-remote-server-instance.png b/en/developer-docs/docs/assets/img/develop-components/micro-integrator/define-a-remote-server-instance.png similarity index 100% rename from en/docs/assets/img/develop-components/micro-integrator/define-a-remote-server-instance.png rename to en/developer-docs/docs/assets/img/develop-components/micro-integrator/define-a-remote-server-instance.png diff --git a/en/docs/assets/img/develop-components/micro-integrator/env_variables.png b/en/developer-docs/docs/assets/img/develop-components/micro-integrator/env_variables.png similarity index 100% rename from en/docs/assets/img/develop-components/micro-integrator/env_variables.png rename to en/developer-docs/docs/assets/img/develop-components/micro-integrator/env_variables.png diff --git a/en/docs/assets/img/develop-components/micro-integrator/libs_dir.png b/en/developer-docs/docs/assets/img/develop-components/micro-integrator/libs_dir.png similarity index 100% rename from en/docs/assets/img/develop-components/micro-integrator/libs_dir.png rename to en/developer-docs/docs/assets/img/develop-components/micro-integrator/libs_dir.png diff --git a/en/docs/assets/img/develop-components/micro-integrator/openapi_file.png b/en/developer-docs/docs/assets/img/develop-components/micro-integrator/openapi_file.png similarity index 100% rename from en/docs/assets/img/develop-components/micro-integrator/openapi_file.png rename to en/developer-docs/docs/assets/img/develop-components/micro-integrator/openapi_file.png diff --git a/en/docs/assets/img/develop-components/micro-integrator/project-runtime-version.png b/en/developer-docs/docs/assets/img/develop-components/micro-integrator/project-runtime-version.png similarity index 100% rename from en/docs/assets/img/develop-components/micro-integrator/project-runtime-version.png rename to en/developer-docs/docs/assets/img/develop-components/micro-integrator/project-runtime-version.png diff --git a/en/docs/assets/img/develop-components/micro-integrator/redeploy-project.png b/en/developer-docs/docs/assets/img/develop-components/micro-integrator/redeploy-project.png similarity index 100% rename from en/docs/assets/img/develop-components/micro-integrator/redeploy-project.png rename to en/developer-docs/docs/assets/img/develop-components/micro-integrator/redeploy-project.png diff --git a/en/docs/assets/img/develop-components/micro-integrator/runtime_version_in_logs.png b/en/developer-docs/docs/assets/img/develop-components/micro-integrator/runtime_version_in_logs.png similarity index 100% rename from en/docs/assets/img/develop-components/micro-integrator/runtime_version_in_logs.png rename to en/developer-docs/docs/assets/img/develop-components/micro-integrator/runtime_version_in_logs.png diff --git a/en/docs/assets/img/develop-components/micro-integrator/set-server-url.png b/en/developer-docs/docs/assets/img/develop-components/micro-integrator/set-server-url.png similarity index 100% rename from en/docs/assets/img/develop-components/micro-integrator/set-server-url.png rename to en/developer-docs/docs/assets/img/develop-components/micro-integrator/set-server-url.png diff --git a/en/docs/assets/img/develop-components/micro-integrator/specify_runtime_version.png b/en/developer-docs/docs/assets/img/develop-components/micro-integrator/specify_runtime_version.png similarity index 100% rename from en/docs/assets/img/develop-components/micro-integrator/specify_runtime_version.png rename to en/developer-docs/docs/assets/img/develop-components/micro-integrator/specify_runtime_version.png diff --git a/en/docs/assets/img/develop-components/micro-integrator/update_runtime_version.png b/en/developer-docs/docs/assets/img/develop-components/micro-integrator/update_runtime_version.png similarity index 100% rename from en/docs/assets/img/develop-components/micro-integrator/update_runtime_version.png rename to en/developer-docs/docs/assets/img/develop-components/micro-integrator/update_runtime_version.png diff --git a/en/docs/assets/img/develop-components/micro-integrator/version-string.png b/en/developer-docs/docs/assets/img/develop-components/micro-integrator/version-string.png similarity index 100% rename from en/docs/assets/img/develop-components/micro-integrator/version-string.png rename to en/developer-docs/docs/assets/img/develop-components/micro-integrator/version-string.png diff --git a/en/docs/assets/img/devops-and-ci-cd/configs/create-env-vars.png b/en/developer-docs/docs/assets/img/devops-and-ci-cd/configs/create-env-vars.png similarity index 100% rename from en/docs/assets/img/devops-and-ci-cd/configs/create-env-vars.png rename to en/developer-docs/docs/assets/img/devops-and-ci-cd/configs/create-env-vars.png diff --git a/en/docs/assets/img/devops-and-ci-cd/configs/create-file-mount.png b/en/developer-docs/docs/assets/img/devops-and-ci-cd/configs/create-file-mount.png similarity index 100% rename from en/docs/assets/img/devops-and-ci-cd/configs/create-file-mount.png rename to en/developer-docs/docs/assets/img/devops-and-ci-cd/configs/create-file-mount.png diff --git a/en/docs/assets/img/devops-and-ci-cd/configs/create-or-delete-config.png b/en/developer-docs/docs/assets/img/devops-and-ci-cd/configs/create-or-delete-config.png similarity index 100% rename from en/docs/assets/img/devops-and-ci-cd/configs/create-or-delete-config.png rename to en/developer-docs/docs/assets/img/devops-and-ci-cd/configs/create-or-delete-config.png diff --git a/en/docs/assets/img/devops-and-ci-cd/containers/containers-view.png b/en/developer-docs/docs/assets/img/devops-and-ci-cd/containers/containers-view.png similarity index 100% rename from en/docs/assets/img/devops-and-ci-cd/containers/containers-view.png rename to en/developer-docs/docs/assets/img/devops-and-ci-cd/containers/containers-view.png diff --git a/en/docs/assets/img/devops-and-ci-cd/containers/edit-container-form.png b/en/developer-docs/docs/assets/img/devops-and-ci-cd/containers/edit-container-form.png similarity index 100% rename from en/docs/assets/img/devops-and-ci-cd/containers/edit-container-form.png rename to en/developer-docs/docs/assets/img/devops-and-ci-cd/containers/edit-container-form.png diff --git a/en/docs/assets/img/devops-and-ci-cd/containers/example-container-cmd-and-args.png b/en/developer-docs/docs/assets/img/devops-and-ci-cd/containers/example-container-cmd-and-args.png similarity index 100% rename from en/docs/assets/img/devops-and-ci-cd/containers/example-container-cmd-and-args.png rename to en/developer-docs/docs/assets/img/devops-and-ci-cd/containers/example-container-cmd-and-args.png diff --git a/en/docs/assets/img/devops-and-ci-cd/healthchecks/confgure-probes.png b/en/developer-docs/docs/assets/img/devops-and-ci-cd/healthchecks/confgure-probes.png similarity index 100% rename from en/docs/assets/img/devops-and-ci-cd/healthchecks/confgure-probes.png rename to en/developer-docs/docs/assets/img/devops-and-ci-cd/healthchecks/confgure-probes.png diff --git a/en/docs/assets/img/devops-and-ci-cd/healthchecks/http-get-probe.png b/en/developer-docs/docs/assets/img/devops-and-ci-cd/healthchecks/http-get-probe.png similarity index 100% rename from en/docs/assets/img/devops-and-ci-cd/healthchecks/http-get-probe.png rename to en/developer-docs/docs/assets/img/devops-and-ci-cd/healthchecks/http-get-probe.png diff --git a/en/docs/assets/img/devops-and-ci-cd/runtime/container-conditions-and-events.png b/en/developer-docs/docs/assets/img/devops-and-ci-cd/runtime/container-conditions-and-events.png similarity index 100% rename from en/docs/assets/img/devops-and-ci-cd/runtime/container-conditions-and-events.png rename to en/developer-docs/docs/assets/img/devops-and-ci-cd/runtime/container-conditions-and-events.png diff --git a/en/docs/assets/img/devops-and-ci-cd/runtime/realtime-container-logs.png b/en/developer-docs/docs/assets/img/devops-and-ci-cd/runtime/realtime-container-logs.png similarity index 100% rename from en/docs/assets/img/devops-and-ci-cd/runtime/realtime-container-logs.png rename to en/developer-docs/docs/assets/img/devops-and-ci-cd/runtime/realtime-container-logs.png diff --git a/en/docs/assets/img/devops-and-ci-cd/runtime/running-instaces.png b/en/developer-docs/docs/assets/img/devops-and-ci-cd/runtime/running-instaces.png similarity index 100% rename from en/docs/assets/img/devops-and-ci-cd/runtime/running-instaces.png rename to en/developer-docs/docs/assets/img/devops-and-ci-cd/runtime/running-instaces.png diff --git a/en/docs/assets/img/devops-and-ci-cd/runtime/runtime-view.png b/en/developer-docs/docs/assets/img/devops-and-ci-cd/runtime/runtime-view.png similarity index 100% rename from en/docs/assets/img/devops-and-ci-cd/runtime/runtime-view.png rename to en/developer-docs/docs/assets/img/devops-and-ci-cd/runtime/runtime-view.png diff --git a/en/docs/assets/img/devops-and-ci-cd/scaling/free-user-scaling-view.png b/en/developer-docs/docs/assets/img/devops-and-ci-cd/scaling/free-user-scaling-view.png similarity index 100% rename from en/docs/assets/img/devops-and-ci-cd/scaling/free-user-scaling-view.png rename to en/developer-docs/docs/assets/img/devops-and-ci-cd/scaling/free-user-scaling-view.png diff --git a/en/docs/assets/img/devops-and-ci-cd/scaling/paid-user-scaling-view.png b/en/developer-docs/docs/assets/img/devops-and-ci-cd/scaling/paid-user-scaling-view.png similarity index 100% rename from en/docs/assets/img/devops-and-ci-cd/scaling/paid-user-scaling-view.png rename to en/developer-docs/docs/assets/img/devops-and-ci-cd/scaling/paid-user-scaling-view.png diff --git a/en/docs/assets/img/devops-and-ci-cd/scaling/scale-to-zero-in-deploy-view.png b/en/developer-docs/docs/assets/img/devops-and-ci-cd/scaling/scale-to-zero-in-deploy-view.png similarity index 100% rename from en/docs/assets/img/devops-and-ci-cd/scaling/scale-to-zero-in-deploy-view.png rename to en/developer-docs/docs/assets/img/devops-and-ci-cd/scaling/scale-to-zero-in-deploy-view.png diff --git a/en/docs/assets/img/devops-and-ci-cd/scaling/scale-to-zero-view.png b/en/developer-docs/docs/assets/img/devops-and-ci-cd/scaling/scale-to-zero-view.png similarity index 100% rename from en/docs/assets/img/devops-and-ci-cd/scaling/scale-to-zero-view.png rename to en/developer-docs/docs/assets/img/devops-and-ci-cd/scaling/scale-to-zero-view.png diff --git a/en/docs/assets/img/devops-and-ci-cd/scaling/scaling-view.png b/en/developer-docs/docs/assets/img/devops-and-ci-cd/scaling/scaling-view.png similarity index 100% rename from en/docs/assets/img/devops-and-ci-cd/scaling/scaling-view.png rename to en/developer-docs/docs/assets/img/devops-and-ci-cd/scaling/scaling-view.png diff --git a/en/docs/assets/img/devops-and-ci-cd/storage/create-emptydir-step-1.png b/en/developer-docs/docs/assets/img/devops-and-ci-cd/storage/create-emptydir-step-1.png similarity index 100% rename from en/docs/assets/img/devops-and-ci-cd/storage/create-emptydir-step-1.png rename to en/developer-docs/docs/assets/img/devops-and-ci-cd/storage/create-emptydir-step-1.png diff --git a/en/docs/assets/img/devops-and-ci-cd/storage/create-emptydir-step-2.png b/en/developer-docs/docs/assets/img/devops-and-ci-cd/storage/create-emptydir-step-2.png similarity index 100% rename from en/docs/assets/img/devops-and-ci-cd/storage/create-emptydir-step-2.png rename to en/developer-docs/docs/assets/img/devops-and-ci-cd/storage/create-emptydir-step-2.png diff --git a/en/docs/assets/img/devops-and-ci-cd/storage/create-pv.png b/en/developer-docs/docs/assets/img/devops-and-ci-cd/storage/create-pv.png similarity index 100% rename from en/docs/assets/img/devops-and-ci-cd/storage/create-pv.png rename to en/developer-docs/docs/assets/img/devops-and-ci-cd/storage/create-pv.png diff --git a/en/docs/assets/img/devops-and-ci-cd/tailscale/deployment-architecture.png b/en/developer-docs/docs/assets/img/devops-and-ci-cd/tailscale/deployment-architecture.png similarity index 100% rename from en/docs/assets/img/devops-and-ci-cd/tailscale/deployment-architecture.png rename to en/developer-docs/docs/assets/img/devops-and-ci-cd/tailscale/deployment-architecture.png diff --git a/en/docs/assets/img/devops-and-ci-cd/tailscale/tailscale-proxy-deployment.png b/en/developer-docs/docs/assets/img/devops-and-ci-cd/tailscale/tailscale-proxy-deployment.png similarity index 100% rename from en/docs/assets/img/devops-and-ci-cd/tailscale/tailscale-proxy-deployment.png rename to en/developer-docs/docs/assets/img/devops-and-ci-cd/tailscale/tailscale-proxy-deployment.png diff --git a/en/docs/assets/img/home/api.svg b/en/developer-docs/docs/assets/img/home/api.svg similarity index 100% rename from en/docs/assets/img/home/api.svg rename to en/developer-docs/docs/assets/img/home/api.svg diff --git a/en/docs/assets/img/home/background.svg b/en/developer-docs/docs/assets/img/home/background.svg similarity index 100% rename from en/docs/assets/img/home/background.svg rename to en/developer-docs/docs/assets/img/home/background.svg diff --git a/en/docs/assets/img/home/integrations.svg b/en/developer-docs/docs/assets/img/home/integrations.svg similarity index 100% rename from en/docs/assets/img/home/integrations.svg rename to en/developer-docs/docs/assets/img/home/integrations.svg diff --git a/en/docs/assets/img/home/services.svg b/en/developer-docs/docs/assets/img/home/services.svg similarity index 100% rename from en/docs/assets/img/home/services.svg rename to en/developer-docs/docs/assets/img/home/services.svg diff --git a/en/docs/assets/img/logo.png b/en/developer-docs/docs/assets/img/logo.png similarity index 100% rename from en/docs/assets/img/logo.png rename to en/developer-docs/docs/assets/img/logo.png diff --git a/en/developer-docs/docs/assets/img/monitoring-and-insights/alerts/alert-creation.png b/en/developer-docs/docs/assets/img/monitoring-and-insights/alerts/alert-creation.png new file mode 100644 index 000000000..c076e56d3 Binary files /dev/null and b/en/developer-docs/docs/assets/img/monitoring-and-insights/alerts/alert-creation.png differ diff --git a/en/developer-docs/docs/assets/img/monitoring-and-insights/alerts/email-notification.png b/en/developer-docs/docs/assets/img/monitoring-and-insights/alerts/email-notification.png new file mode 100644 index 000000000..229c6c5b9 Binary files /dev/null and b/en/developer-docs/docs/assets/img/monitoring-and-insights/alerts/email-notification.png differ diff --git a/en/docs/assets/img/monitoring-and-insights/api-insights/alert-summary.png b/en/developer-docs/docs/assets/img/monitoring-and-insights/api-insights/alert-summary.png similarity index 100% rename from en/docs/assets/img/monitoring-and-insights/api-insights/alert-summary.png rename to en/developer-docs/docs/assets/img/monitoring-and-insights/api-insights/alert-summary.png diff --git a/en/docs/assets/img/monitoring-and-insights/api-insights/alerts-page-full.png b/en/developer-docs/docs/assets/img/monitoring-and-insights/api-insights/alerts-page-full.png similarity index 100% rename from en/docs/assets/img/monitoring-and-insights/api-insights/alerts-page-full.png rename to en/developer-docs/docs/assets/img/monitoring-and-insights/api-insights/alerts-page-full.png diff --git a/en/docs/assets/img/monitoring-and-insights/api-insights/api-usage-timeline.png b/en/developer-docs/docs/assets/img/monitoring-and-insights/api-insights/api-usage-timeline.png similarity index 100% rename from en/docs/assets/img/monitoring-and-insights/api-insights/api-usage-timeline.png rename to en/developer-docs/docs/assets/img/monitoring-and-insights/api-insights/api-usage-timeline.png diff --git a/en/docs/assets/img/monitoring-and-insights/api-insights/cache-latency.png b/en/developer-docs/docs/assets/img/monitoring-and-insights/api-insights/cache-latency.png similarity index 100% rename from en/docs/assets/img/monitoring-and-insights/api-insights/cache-latency.png rename to en/developer-docs/docs/assets/img/monitoring-and-insights/api-insights/cache-latency.png diff --git a/en/docs/assets/img/monitoring-and-insights/api-insights/cache-page-full.png b/en/developer-docs/docs/assets/img/monitoring-and-insights/api-insights/cache-page-full.png similarity index 100% rename from en/docs/assets/img/monitoring-and-insights/api-insights/cache-page-full.png rename to en/developer-docs/docs/assets/img/monitoring-and-insights/api-insights/cache-page-full.png diff --git a/en/docs/assets/img/monitoring-and-insights/api-insights/cache-statistics.png b/en/developer-docs/docs/assets/img/monitoring-and-insights/api-insights/cache-statistics.png similarity index 100% rename from en/docs/assets/img/monitoring-and-insights/api-insights/cache-statistics.png rename to en/developer-docs/docs/assets/img/monitoring-and-insights/api-insights/cache-statistics.png diff --git a/en/docs/assets/img/monitoring-and-insights/api-insights/choreo-system-home.png b/en/developer-docs/docs/assets/img/monitoring-and-insights/api-insights/choreo-system-home.png similarity index 100% rename from en/docs/assets/img/monitoring-and-insights/api-insights/choreo-system-home.png rename to en/developer-docs/docs/assets/img/monitoring-and-insights/api-insights/choreo-system-home.png diff --git a/en/docs/assets/img/monitoring-and-insights/api-insights/configured-report.png b/en/developer-docs/docs/assets/img/monitoring-and-insights/api-insights/configured-report.png similarity index 100% rename from en/docs/assets/img/monitoring-and-insights/api-insights/configured-report.png rename to en/developer-docs/docs/assets/img/monitoring-and-insights/api-insights/configured-report.png diff --git a/en/docs/assets/img/monitoring-and-insights/api-insights/create-application-wizard.png b/en/developer-docs/docs/assets/img/monitoring-and-insights/api-insights/create-application-wizard.png similarity index 100% rename from en/docs/assets/img/monitoring-and-insights/api-insights/create-application-wizard.png rename to en/developer-docs/docs/assets/img/monitoring-and-insights/api-insights/create-application-wizard.png diff --git a/en/docs/assets/img/monitoring-and-insights/api-insights/create-application.png b/en/developer-docs/docs/assets/img/monitoring-and-insights/api-insights/create-application.png similarity index 100% rename from en/docs/assets/img/monitoring-and-insights/api-insights/create-application.png rename to en/developer-docs/docs/assets/img/monitoring-and-insights/api-insights/create-application.png diff --git a/en/docs/assets/img/monitoring-and-insights/api-insights/custom-report-sample.png b/en/developer-docs/docs/assets/img/monitoring-and-insights/api-insights/custom-report-sample.png similarity index 100% rename from en/docs/assets/img/monitoring-and-insights/api-insights/custom-report-sample.png rename to en/developer-docs/docs/assets/img/monitoring-and-insights/api-insights/custom-report-sample.png diff --git a/en/docs/assets/img/monitoring-and-insights/api-insights/custom-report.png b/en/developer-docs/docs/assets/img/monitoring-and-insights/api-insights/custom-report.png similarity index 100% rename from en/docs/assets/img/monitoring-and-insights/api-insights/custom-report.png rename to en/developer-docs/docs/assets/img/monitoring-and-insights/api-insights/custom-report.png diff --git a/en/docs/assets/img/monitoring-and-insights/api-insights/custom-reports-step-1.png b/en/developer-docs/docs/assets/img/monitoring-and-insights/api-insights/custom-reports-step-1.png similarity index 100% rename from en/docs/assets/img/monitoring-and-insights/api-insights/custom-reports-step-1.png rename to en/developer-docs/docs/assets/img/monitoring-and-insights/api-insights/custom-reports-step-1.png diff --git a/en/docs/assets/img/monitoring-and-insights/api-insights/custom-reports-step-2-to-4.png b/en/developer-docs/docs/assets/img/monitoring-and-insights/api-insights/custom-reports-step-2-to-4.png similarity index 100% rename from en/docs/assets/img/monitoring-and-insights/api-insights/custom-reports-step-2-to-4.png rename to en/developer-docs/docs/assets/img/monitoring-and-insights/api-insights/custom-reports-step-2-to-4.png diff --git a/en/docs/assets/img/monitoring-and-insights/api-insights/custom-reports-step-5.png b/en/developer-docs/docs/assets/img/monitoring-and-insights/api-insights/custom-reports-step-5.png similarity index 100% rename from en/docs/assets/img/monitoring-and-insights/api-insights/custom-reports-step-5.png rename to en/developer-docs/docs/assets/img/monitoring-and-insights/api-insights/custom-reports-step-5.png diff --git a/en/docs/assets/img/monitoring-and-insights/api-insights/custom-reports-step-6.png b/en/developer-docs/docs/assets/img/monitoring-and-insights/api-insights/custom-reports-step-6.png similarity index 100% rename from en/docs/assets/img/monitoring-and-insights/api-insights/custom-reports-step-6.png rename to en/developer-docs/docs/assets/img/monitoring-and-insights/api-insights/custom-reports-step-6.png diff --git a/en/docs/assets/img/monitoring-and-insights/api-insights/custom-reports-step-7.png b/en/developer-docs/docs/assets/img/monitoring-and-insights/api-insights/custom-reports-step-7.png similarity index 100% rename from en/docs/assets/img/monitoring-and-insights/api-insights/custom-reports-step-7.png rename to en/developer-docs/docs/assets/img/monitoring-and-insights/api-insights/custom-reports-step-7.png diff --git a/en/docs/assets/img/monitoring-and-insights/api-insights/devices-page-full.png b/en/developer-docs/docs/assets/img/monitoring-and-insights/api-insights/devices-page-full.png similarity index 100% rename from en/docs/assets/img/monitoring-and-insights/api-insights/devices-page-full.png rename to en/developer-docs/docs/assets/img/monitoring-and-insights/api-insights/devices-page-full.png diff --git a/en/docs/assets/img/monitoring-and-insights/api-insights/endpoints.png b/en/developer-docs/docs/assets/img/monitoring-and-insights/api-insights/endpoints.png similarity index 100% rename from en/docs/assets/img/monitoring-and-insights/api-insights/endpoints.png rename to en/developer-docs/docs/assets/img/monitoring-and-insights/api-insights/endpoints.png diff --git a/en/docs/assets/img/monitoring-and-insights/api-insights/error-by-status-code.png b/en/developer-docs/docs/assets/img/monitoring-and-insights/api-insights/error-by-status-code.png similarity index 100% rename from en/docs/assets/img/monitoring-and-insights/api-insights/error-by-status-code.png rename to en/developer-docs/docs/assets/img/monitoring-and-insights/api-insights/error-by-status-code.png diff --git a/en/docs/assets/img/monitoring-and-insights/api-insights/error-category-graph.png b/en/developer-docs/docs/assets/img/monitoring-and-insights/api-insights/error-category-graph.png similarity index 100% rename from en/docs/assets/img/monitoring-and-insights/api-insights/error-category-graph.png rename to en/developer-docs/docs/assets/img/monitoring-and-insights/api-insights/error-category-graph.png diff --git a/en/docs/assets/img/monitoring-and-insights/api-insights/error-category-table.png b/en/developer-docs/docs/assets/img/monitoring-and-insights/api-insights/error-category-table.png similarity index 100% rename from en/docs/assets/img/monitoring-and-insights/api-insights/error-category-table.png rename to en/developer-docs/docs/assets/img/monitoring-and-insights/api-insights/error-category-table.png diff --git a/en/docs/assets/img/monitoring-and-insights/api-insights/error-heatmap.png b/en/developer-docs/docs/assets/img/monitoring-and-insights/api-insights/error-heatmap.png similarity index 100% rename from en/docs/assets/img/monitoring-and-insights/api-insights/error-heatmap.png rename to en/developer-docs/docs/assets/img/monitoring-and-insights/api-insights/error-heatmap.png diff --git a/en/docs/assets/img/monitoring-and-insights/api-insights/error-page-full.png b/en/developer-docs/docs/assets/img/monitoring-and-insights/api-insights/error-page-full.png similarity index 100% rename from en/docs/assets/img/monitoring-and-insights/api-insights/error-page-full.png rename to en/developer-docs/docs/assets/img/monitoring-and-insights/api-insights/error-page-full.png diff --git a/en/docs/assets/img/monitoring-and-insights/api-insights/generate-credentials.png b/en/developer-docs/docs/assets/img/monitoring-and-insights/api-insights/generate-credentials.png similarity index 100% rename from en/docs/assets/img/monitoring-and-insights/api-insights/generate-credentials.png rename to en/developer-docs/docs/assets/img/monitoring-and-insights/api-insights/generate-credentials.png diff --git a/en/docs/assets/img/monitoring-and-insights/api-insights/geomap-hit-count-scale.png b/en/developer-docs/docs/assets/img/monitoring-and-insights/api-insights/geomap-hit-count-scale.png similarity index 100% rename from en/docs/assets/img/monitoring-and-insights/api-insights/geomap-hit-count-scale.png rename to en/developer-docs/docs/assets/img/monitoring-and-insights/api-insights/geomap-hit-count-scale.png diff --git a/en/docs/assets/img/monitoring-and-insights/api-insights/geomap-page-full.png b/en/developer-docs/docs/assets/img/monitoring-and-insights/api-insights/geomap-page-full.png similarity index 100% rename from en/docs/assets/img/monitoring-and-insights/api-insights/geomap-page-full.png rename to en/developer-docs/docs/assets/img/monitoring-and-insights/api-insights/geomap-page-full.png diff --git a/en/docs/assets/img/monitoring-and-insights/api-insights/geomap-requests-by-country.png b/en/developer-docs/docs/assets/img/monitoring-and-insights/api-insights/geomap-requests-by-country.png similarity index 100% rename from en/docs/assets/img/monitoring-and-insights/api-insights/geomap-requests-by-country.png rename to en/developer-docs/docs/assets/img/monitoring-and-insights/api-insights/geomap-requests-by-country.png diff --git a/en/docs/assets/img/monitoring-and-insights/api-insights/insights-download-report.svg b/en/developer-docs/docs/assets/img/monitoring-and-insights/api-insights/insights-download-report.svg similarity index 100% rename from en/docs/assets/img/monitoring-and-insights/api-insights/insights-download-report.svg rename to en/developer-docs/docs/assets/img/monitoring-and-insights/api-insights/insights-download-report.svg diff --git a/en/docs/assets/img/monitoring-and-insights/api-insights/latency-by-category.png b/en/developer-docs/docs/assets/img/monitoring-and-insights/api-insights/latency-by-category.png similarity index 100% rename from en/docs/assets/img/monitoring-and-insights/api-insights/latency-by-category.png rename to en/developer-docs/docs/assets/img/monitoring-and-insights/api-insights/latency-by-category.png diff --git a/en/docs/assets/img/monitoring-and-insights/api-insights/latency-page-full.png b/en/developer-docs/docs/assets/img/monitoring-and-insights/api-insights/latency-page-full.png similarity index 100% rename from en/docs/assets/img/monitoring-and-insights/api-insights/latency-page-full.png rename to en/developer-docs/docs/assets/img/monitoring-and-insights/api-insights/latency-page-full.png diff --git a/en/docs/assets/img/monitoring-and-insights/api-insights/overview-page-error-rate.png b/en/developer-docs/docs/assets/img/monitoring-and-insights/api-insights/overview-page-error-rate.png similarity index 100% rename from en/docs/assets/img/monitoring-and-insights/api-insights/overview-page-error-rate.png rename to en/developer-docs/docs/assets/img/monitoring-and-insights/api-insights/overview-page-error-rate.png diff --git a/en/docs/assets/img/monitoring-and-insights/api-insights/overview-page-error-request-count.png b/en/developer-docs/docs/assets/img/monitoring-and-insights/api-insights/overview-page-error-request-count.png similarity index 100% rename from en/docs/assets/img/monitoring-and-insights/api-insights/overview-page-error-request-count.png rename to en/developer-docs/docs/assets/img/monitoring-and-insights/api-insights/overview-page-error-request-count.png diff --git a/en/docs/assets/img/monitoring-and-insights/api-insights/overview-page-latency.png b/en/developer-docs/docs/assets/img/monitoring-and-insights/api-insights/overview-page-latency.png similarity index 100% rename from en/docs/assets/img/monitoring-and-insights/api-insights/overview-page-latency.png rename to en/developer-docs/docs/assets/img/monitoring-and-insights/api-insights/overview-page-latency.png diff --git a/en/docs/assets/img/monitoring-and-insights/api-insights/overview-page-timeline.png b/en/developer-docs/docs/assets/img/monitoring-and-insights/api-insights/overview-page-timeline.png similarity index 100% rename from en/docs/assets/img/monitoring-and-insights/api-insights/overview-page-timeline.png rename to en/developer-docs/docs/assets/img/monitoring-and-insights/api-insights/overview-page-timeline.png diff --git a/en/docs/assets/img/monitoring-and-insights/api-insights/overview-page-total-traffic.png b/en/developer-docs/docs/assets/img/monitoring-and-insights/api-insights/overview-page-total-traffic.png similarity index 100% rename from en/docs/assets/img/monitoring-and-insights/api-insights/overview-page-total-traffic.png rename to en/developer-docs/docs/assets/img/monitoring-and-insights/api-insights/overview-page-total-traffic.png diff --git a/en/docs/assets/img/monitoring-and-insights/api-insights/overview.png b/en/developer-docs/docs/assets/img/monitoring-and-insights/api-insights/overview.png similarity index 100% rename from en/docs/assets/img/monitoring-and-insights/api-insights/overview.png rename to en/developer-docs/docs/assets/img/monitoring-and-insights/api-insights/overview.png diff --git a/en/docs/assets/img/monitoring-and-insights/api-insights/report-page-full.png b/en/developer-docs/docs/assets/img/monitoring-and-insights/api-insights/report-page-full.png similarity index 100% rename from en/docs/assets/img/monitoring-and-insights/api-insights/report-page-full.png rename to en/developer-docs/docs/assets/img/monitoring-and-insights/api-insights/report-page-full.png diff --git a/en/docs/assets/img/monitoring-and-insights/api-insights/request-access.png b/en/developer-docs/docs/assets/img/monitoring-and-insights/api-insights/request-access.png similarity index 100% rename from en/docs/assets/img/monitoring-and-insights/api-insights/request-access.png rename to en/developer-docs/docs/assets/img/monitoring-and-insights/api-insights/request-access.png diff --git a/en/docs/assets/img/monitoring-and-insights/api-insights/resource-usage.png b/en/developer-docs/docs/assets/img/monitoring-and-insights/api-insights/resource-usage.png similarity index 100% rename from en/docs/assets/img/monitoring-and-insights/api-insights/resource-usage.png rename to en/developer-docs/docs/assets/img/monitoring-and-insights/api-insights/resource-usage.png diff --git a/en/docs/assets/img/monitoring-and-insights/api-insights/slowest-apis.png b/en/developer-docs/docs/assets/img/monitoring-and-insights/api-insights/slowest-apis.png similarity index 100% rename from en/docs/assets/img/monitoring-and-insights/api-insights/slowest-apis.png rename to en/developer-docs/docs/assets/img/monitoring-and-insights/api-insights/slowest-apis.png diff --git a/en/docs/assets/img/monitoring-and-insights/api-insights/subscribe-api.png b/en/developer-docs/docs/assets/img/monitoring-and-insights/api-insights/subscribe-api.png similarity index 100% rename from en/docs/assets/img/monitoring-and-insights/api-insights/subscribe-api.png rename to en/developer-docs/docs/assets/img/monitoring-and-insights/api-insights/subscribe-api.png diff --git a/en/docs/assets/img/monitoring-and-insights/api-insights/target-error-by-status-code.png b/en/developer-docs/docs/assets/img/monitoring-and-insights/api-insights/target-error-by-status-code.png similarity index 100% rename from en/docs/assets/img/monitoring-and-insights/api-insights/target-error-by-status-code.png rename to en/developer-docs/docs/assets/img/monitoring-and-insights/api-insights/target-error-by-status-code.png diff --git a/en/docs/assets/img/monitoring-and-insights/api-insights/target-error-heatmap.png b/en/developer-docs/docs/assets/img/monitoring-and-insights/api-insights/target-error-heatmap.png similarity index 100% rename from en/docs/assets/img/monitoring-and-insights/api-insights/target-error-heatmap.png rename to en/developer-docs/docs/assets/img/monitoring-and-insights/api-insights/target-error-heatmap.png diff --git a/en/docs/assets/img/monitoring-and-insights/api-insights/top-apis-by-alert-count.png b/en/developer-docs/docs/assets/img/monitoring-and-insights/api-insights/top-apis-by-alert-count.png similarity index 100% rename from en/docs/assets/img/monitoring-and-insights/api-insights/top-apis-by-alert-count.png rename to en/developer-docs/docs/assets/img/monitoring-and-insights/api-insights/top-apis-by-alert-count.png diff --git a/en/docs/assets/img/monitoring-and-insights/api-insights/top-platforms.png b/en/developer-docs/docs/assets/img/monitoring-and-insights/api-insights/top-platforms.png similarity index 100% rename from en/docs/assets/img/monitoring-and-insights/api-insights/top-platforms.png rename to en/developer-docs/docs/assets/img/monitoring-and-insights/api-insights/top-platforms.png diff --git a/en/docs/assets/img/monitoring-and-insights/api-insights/top-user-agents.png b/en/developer-docs/docs/assets/img/monitoring-and-insights/api-insights/top-user-agents.png similarity index 100% rename from en/docs/assets/img/monitoring-and-insights/api-insights/top-user-agents.png rename to en/developer-docs/docs/assets/img/monitoring-and-insights/api-insights/top-user-agents.png diff --git a/en/docs/assets/img/monitoring-and-insights/api-insights/traffic-page-full.png b/en/developer-docs/docs/assets/img/monitoring-and-insights/api-insights/traffic-page-full.png similarity index 100% rename from en/docs/assets/img/monitoring-and-insights/api-insights/traffic-page-full.png rename to en/developer-docs/docs/assets/img/monitoring-and-insights/api-insights/traffic-page-full.png diff --git a/en/docs/assets/img/monitoring-and-insights/api-insights/update-token-expirary-time.png b/en/developer-docs/docs/assets/img/monitoring-and-insights/api-insights/update-token-expirary-time.png similarity index 100% rename from en/docs/assets/img/monitoring-and-insights/api-insights/update-token-expirary-time.png rename to en/developer-docs/docs/assets/img/monitoring-and-insights/api-insights/update-token-expirary-time.png diff --git a/en/docs/assets/img/monitoring-and-insights/api-insights/usage-by-application.png b/en/developer-docs/docs/assets/img/monitoring-and-insights/api-insights/usage-by-application.png similarity index 100% rename from en/docs/assets/img/monitoring-and-insights/api-insights/usage-by-application.png rename to en/developer-docs/docs/assets/img/monitoring-and-insights/api-insights/usage-by-application.png diff --git a/en/docs/assets/img/monitoring-and-insights/api-insights/usage-by-target.png b/en/developer-docs/docs/assets/img/monitoring-and-insights/api-insights/usage-by-target.png similarity index 100% rename from en/docs/assets/img/monitoring-and-insights/api-insights/usage-by-target.png rename to en/developer-docs/docs/assets/img/monitoring-and-insights/api-insights/usage-by-target.png diff --git a/en/docs/assets/img/monitoring-and-insights/data_recieved_moesif_notification.png b/en/developer-docs/docs/assets/img/monitoring-and-insights/data_recieved_moesif_notification.png similarity index 100% rename from en/docs/assets/img/monitoring-and-insights/data_recieved_moesif_notification.png rename to en/developer-docs/docs/assets/img/monitoring-and-insights/data_recieved_moesif_notification.png diff --git a/en/docs/assets/img/monitoring-and-insights/engineering-insights/add-integration-cio-dashboard.png b/en/developer-docs/docs/assets/img/monitoring-and-insights/engineering-insights/add-integration-cio-dashboard.png similarity index 100% rename from en/docs/assets/img/monitoring-and-insights/engineering-insights/add-integration-cio-dashboard.png rename to en/developer-docs/docs/assets/img/monitoring-and-insights/engineering-insights/add-integration-cio-dashboard.png diff --git a/en/docs/assets/img/monitoring-and-insights/engineering-insights/add-integration-configure.png b/en/developer-docs/docs/assets/img/monitoring-and-insights/engineering-insights/add-integration-configure.png similarity index 100% rename from en/docs/assets/img/monitoring-and-insights/engineering-insights/add-integration-configure.png rename to en/developer-docs/docs/assets/img/monitoring-and-insights/engineering-insights/add-integration-configure.png diff --git a/en/docs/assets/img/monitoring-and-insights/engineering-insights/change-failure-rate-chart.png b/en/developer-docs/docs/assets/img/monitoring-and-insights/engineering-insights/change-failure-rate-chart.png similarity index 100% rename from en/docs/assets/img/monitoring-and-insights/engineering-insights/change-failure-rate-chart.png rename to en/developer-docs/docs/assets/img/monitoring-and-insights/engineering-insights/change-failure-rate-chart.png diff --git a/en/docs/assets/img/monitoring-and-insights/engineering-insights/change-failure-rate-summary.png b/en/developer-docs/docs/assets/img/monitoring-and-insights/engineering-insights/change-failure-rate-summary.png similarity index 100% rename from en/docs/assets/img/monitoring-and-insights/engineering-insights/change-failure-rate-summary.png rename to en/developer-docs/docs/assets/img/monitoring-and-insights/engineering-insights/change-failure-rate-summary.png diff --git a/en/docs/assets/img/monitoring-and-insights/engineering-insights/cio-dashboard.png b/en/developer-docs/docs/assets/img/monitoring-and-insights/engineering-insights/cio-dashboard.png similarity index 100% rename from en/docs/assets/img/monitoring-and-insights/engineering-insights/cio-dashboard.png rename to en/developer-docs/docs/assets/img/monitoring-and-insights/engineering-insights/cio-dashboard.png diff --git a/en/docs/assets/img/monitoring-and-insights/engineering-insights/deployment-copy-to-clipboard.png b/en/developer-docs/docs/assets/img/monitoring-and-insights/engineering-insights/deployment-copy-to-clipboard.png similarity index 100% rename from en/docs/assets/img/monitoring-and-insights/engineering-insights/deployment-copy-to-clipboard.png rename to en/developer-docs/docs/assets/img/monitoring-and-insights/engineering-insights/deployment-copy-to-clipboard.png diff --git a/en/docs/assets/img/monitoring-and-insights/engineering-insights/deployment-frequency-snapshot.png b/en/developer-docs/docs/assets/img/monitoring-and-insights/engineering-insights/deployment-frequency-snapshot.png similarity index 100% rename from en/docs/assets/img/monitoring-and-insights/engineering-insights/deployment-frequency-snapshot.png rename to en/developer-docs/docs/assets/img/monitoring-and-insights/engineering-insights/deployment-frequency-snapshot.png diff --git a/en/docs/assets/img/monitoring-and-insights/engineering-insights/deployment-frequency-time-series.png b/en/developer-docs/docs/assets/img/monitoring-and-insights/engineering-insights/deployment-frequency-time-series.png similarity index 100% rename from en/docs/assets/img/monitoring-and-insights/engineering-insights/deployment-frequency-time-series.png rename to en/developer-docs/docs/assets/img/monitoring-and-insights/engineering-insights/deployment-frequency-time-series.png diff --git a/en/docs/assets/img/monitoring-and-insights/engineering-insights/deployment-history.png b/en/developer-docs/docs/assets/img/monitoring-and-insights/engineering-insights/deployment-history.png similarity index 100% rename from en/docs/assets/img/monitoring-and-insights/engineering-insights/deployment-history.png rename to en/developer-docs/docs/assets/img/monitoring-and-insights/engineering-insights/deployment-history.png diff --git a/en/docs/assets/img/monitoring-and-insights/engineering-insights/dora-matrix.png b/en/developer-docs/docs/assets/img/monitoring-and-insights/engineering-insights/dora-matrix.png similarity index 100% rename from en/docs/assets/img/monitoring-and-insights/engineering-insights/dora-matrix.png rename to en/developer-docs/docs/assets/img/monitoring-and-insights/engineering-insights/dora-matrix.png diff --git a/en/docs/assets/img/monitoring-and-insights/engineering-insights/dora-metrics-summary.png b/en/developer-docs/docs/assets/img/monitoring-and-insights/engineering-insights/dora-metrics-summary.png similarity index 100% rename from en/docs/assets/img/monitoring-and-insights/engineering-insights/dora-metrics-summary.png rename to en/developer-docs/docs/assets/img/monitoring-and-insights/engineering-insights/dora-metrics-summary.png diff --git a/en/docs/assets/img/monitoring-and-insights/engineering-insights/edit-configurations.png b/en/developer-docs/docs/assets/img/monitoring-and-insights/engineering-insights/edit-configurations.png similarity index 100% rename from en/docs/assets/img/monitoring-and-insights/engineering-insights/edit-configurations.png rename to en/developer-docs/docs/assets/img/monitoring-and-insights/engineering-insights/edit-configurations.png diff --git a/en/docs/assets/img/monitoring-and-insights/engineering-insights/enable-dora-metrics.png b/en/developer-docs/docs/assets/img/monitoring-and-insights/engineering-insights/enable-dora-metrics.png similarity index 100% rename from en/docs/assets/img/monitoring-and-insights/engineering-insights/enable-dora-metrics.png rename to en/developer-docs/docs/assets/img/monitoring-and-insights/engineering-insights/enable-dora-metrics.png diff --git a/en/docs/assets/img/monitoring-and-insights/engineering-insights/filter-label.png b/en/developer-docs/docs/assets/img/monitoring-and-insights/engineering-insights/filter-label.png similarity index 100% rename from en/docs/assets/img/monitoring-and-insights/engineering-insights/filter-label.png rename to en/developer-docs/docs/assets/img/monitoring-and-insights/engineering-insights/filter-label.png diff --git a/en/docs/assets/img/monitoring-and-insights/engineering-insights/lead-time-for-a-change-chart.png b/en/developer-docs/docs/assets/img/monitoring-and-insights/engineering-insights/lead-time-for-a-change-chart.png similarity index 100% rename from en/docs/assets/img/monitoring-and-insights/engineering-insights/lead-time-for-a-change-chart.png rename to en/developer-docs/docs/assets/img/monitoring-and-insights/engineering-insights/lead-time-for-a-change-chart.png diff --git a/en/docs/assets/img/monitoring-and-insights/engineering-insights/lead-time-for-a-change-summary.png b/en/developer-docs/docs/assets/img/monitoring-and-insights/engineering-insights/lead-time-for-a-change-summary.png similarity index 100% rename from en/docs/assets/img/monitoring-and-insights/engineering-insights/lead-time-for-a-change-summary.png rename to en/developer-docs/docs/assets/img/monitoring-and-insights/engineering-insights/lead-time-for-a-change-summary.png diff --git a/en/docs/assets/img/monitoring-and-insights/engineering-insights/mean-time-to-recovery-chart.png b/en/developer-docs/docs/assets/img/monitoring-and-insights/engineering-insights/mean-time-to-recovery-chart.png similarity index 100% rename from en/docs/assets/img/monitoring-and-insights/engineering-insights/mean-time-to-recovery-chart.png rename to en/developer-docs/docs/assets/img/monitoring-and-insights/engineering-insights/mean-time-to-recovery-chart.png diff --git a/en/docs/assets/img/monitoring-and-insights/engineering-insights/mean-time-to-recovery-summary.png b/en/developer-docs/docs/assets/img/monitoring-and-insights/engineering-insights/mean-time-to-recovery-summary.png similarity index 100% rename from en/docs/assets/img/monitoring-and-insights/engineering-insights/mean-time-to-recovery-summary.png rename to en/developer-docs/docs/assets/img/monitoring-and-insights/engineering-insights/mean-time-to-recovery-summary.png diff --git a/en/docs/assets/img/monitoring-and-insights/engineering-insights/time-series-view.jpg b/en/developer-docs/docs/assets/img/monitoring-and-insights/engineering-insights/time-series-view.jpg similarity index 100% rename from en/docs/assets/img/monitoring-and-insights/engineering-insights/time-series-view.jpg rename to en/developer-docs/docs/assets/img/monitoring-and-insights/engineering-insights/time-series-view.jpg diff --git a/en/docs/assets/img/monitoring-and-insights/first_time_key_moesif.png b/en/developer-docs/docs/assets/img/monitoring-and-insights/first_time_key_moesif.png similarity index 100% rename from en/docs/assets/img/monitoring-and-insights/first_time_key_moesif.png rename to en/developer-docs/docs/assets/img/monitoring-and-insights/first_time_key_moesif.png diff --git a/en/docs/assets/img/monitoring-and-insights/observability/diagnostic-view.png b/en/developer-docs/docs/assets/img/monitoring-and-insights/observability/diagnostic-view.png similarity index 100% rename from en/docs/assets/img/monitoring-and-insights/observability/diagnostic-view.png rename to en/developer-docs/docs/assets/img/monitoring-and-insights/observability/diagnostic-view.png diff --git a/en/docs/assets/img/monitoring-and-insights/observability/logs-panel.png b/en/developer-docs/docs/assets/img/monitoring-and-insights/observability/logs-panel.png similarity index 100% rename from en/docs/assets/img/monitoring-and-insights/observability/logs-panel.png rename to en/developer-docs/docs/assets/img/monitoring-and-insights/observability/logs-panel.png diff --git a/en/docs/assets/img/monitoring-and-insights/observability/logs.png b/en/developer-docs/docs/assets/img/monitoring-and-insights/observability/logs.png similarity index 100% rename from en/docs/assets/img/monitoring-and-insights/observability/logs.png rename to en/developer-docs/docs/assets/img/monitoring-and-insights/observability/logs.png diff --git a/en/docs/assets/img/monitoring-and-insights/observability/overview-overall.png b/en/developer-docs/docs/assets/img/monitoring-and-insights/observability/overview-overall.png similarity index 100% rename from en/docs/assets/img/monitoring-and-insights/observability/overview-overall.png rename to en/developer-docs/docs/assets/img/monitoring-and-insights/observability/overview-overall.png diff --git a/en/docs/assets/img/monitoring-and-insights/observability/throughput-and-latency.png b/en/developer-docs/docs/assets/img/monitoring-and-insights/observability/throughput-and-latency.png similarity index 100% rename from en/docs/assets/img/monitoring-and-insights/observability/throughput-and-latency.png rename to en/developer-docs/docs/assets/img/monitoring-and-insights/observability/throughput-and-latency.png diff --git a/en/docs/assets/img/monitoring-and-insights/observability/view-application-logs.png b/en/developer-docs/docs/assets/img/monitoring-and-insights/observability/view-application-logs.png similarity index 100% rename from en/docs/assets/img/monitoring-and-insights/observability/view-application-logs.png rename to en/developer-docs/docs/assets/img/monitoring-and-insights/observability/view-application-logs.png diff --git a/en/docs/assets/img/monitoring-and-insights/view-logs/audit-logs.png b/en/developer-docs/docs/assets/img/monitoring-and-insights/view-logs/audit-logs.png similarity index 100% rename from en/docs/assets/img/monitoring-and-insights/view-logs/audit-logs.png rename to en/developer-docs/docs/assets/img/monitoring-and-insights/view-logs/audit-logs.png diff --git a/en/docs/assets/img/monitoring-and-insights/view-logs/create-role-to-view-audit-logs.png b/en/developer-docs/docs/assets/img/monitoring-and-insights/view-logs/create-role-to-view-audit-logs.png similarity index 100% rename from en/docs/assets/img/monitoring-and-insights/view-logs/create-role-to-view-audit-logs.png rename to en/developer-docs/docs/assets/img/monitoring-and-insights/view-logs/create-role-to-view-audit-logs.png diff --git a/en/docs/assets/img/monitoring-and-insights/view-logs/log-management-permission.png b/en/developer-docs/docs/assets/img/monitoring-and-insights/view-logs/log-management-permission.png similarity index 100% rename from en/docs/assets/img/monitoring-and-insights/view-logs/log-management-permission.png rename to en/developer-docs/docs/assets/img/monitoring-and-insights/view-logs/log-management-permission.png diff --git a/en/docs/assets/img/monitoring-and-insights/view-logs/runtime-logs.png b/en/developer-docs/docs/assets/img/monitoring-and-insights/view-logs/runtime-logs.png similarity index 100% rename from en/docs/assets/img/monitoring-and-insights/view-logs/runtime-logs.png rename to en/developer-docs/docs/assets/img/monitoring-and-insights/view-logs/runtime-logs.png diff --git a/en/docs/assets/img/monitoring-and-insights/work-with-choreo-insights-api/create-an-application.png b/en/developer-docs/docs/assets/img/monitoring-and-insights/work-with-choreo-insights-api/create-an-application.png similarity index 100% rename from en/docs/assets/img/monitoring-and-insights/work-with-choreo-insights-api/create-an-application.png rename to en/developer-docs/docs/assets/img/monitoring-and-insights/work-with-choreo-insights-api/create-an-application.png diff --git a/en/docs/assets/img/monitoring-and-insights/work-with-choreo-insights-api/create-application.png b/en/developer-docs/docs/assets/img/monitoring-and-insights/work-with-choreo-insights-api/create-application.png similarity index 100% rename from en/docs/assets/img/monitoring-and-insights/work-with-choreo-insights-api/create-application.png rename to en/developer-docs/docs/assets/img/monitoring-and-insights/work-with-choreo-insights-api/create-application.png diff --git a/en/docs/assets/img/monitoring-and-insights/work-with-choreo-insights-api/endpoints.png b/en/developer-docs/docs/assets/img/monitoring-and-insights/work-with-choreo-insights-api/endpoints.png similarity index 100% rename from en/docs/assets/img/monitoring-and-insights/work-with-choreo-insights-api/endpoints.png rename to en/developer-docs/docs/assets/img/monitoring-and-insights/work-with-choreo-insights-api/endpoints.png diff --git a/en/docs/assets/img/monitoring-and-insights/work-with-choreo-insights-api/generate-credentials.png b/en/developer-docs/docs/assets/img/monitoring-and-insights/work-with-choreo-insights-api/generate-credentials.png similarity index 100% rename from en/docs/assets/img/monitoring-and-insights/work-with-choreo-insights-api/generate-credentials.png rename to en/developer-docs/docs/assets/img/monitoring-and-insights/work-with-choreo-insights-api/generate-credentials.png diff --git a/en/docs/assets/img/monitoring-and-insights/work-with-choreo-insights-api/request-access.png b/en/developer-docs/docs/assets/img/monitoring-and-insights/work-with-choreo-insights-api/request-access.png similarity index 100% rename from en/docs/assets/img/monitoring-and-insights/work-with-choreo-insights-api/request-access.png rename to en/developer-docs/docs/assets/img/monitoring-and-insights/work-with-choreo-insights-api/request-access.png diff --git a/en/docs/assets/img/monitoring-and-insights/work-with-choreo-insights-api/subscribe-to-insights-api.png b/en/developer-docs/docs/assets/img/monitoring-and-insights/work-with-choreo-insights-api/subscribe-to-insights-api.png similarity index 100% rename from en/docs/assets/img/monitoring-and-insights/work-with-choreo-insights-api/subscribe-to-insights-api.png rename to en/developer-docs/docs/assets/img/monitoring-and-insights/work-with-choreo-insights-api/subscribe-to-insights-api.png diff --git a/en/docs/assets/img/monitoring-and-insights/work-with-choreo-insights-api/update-token-expirary-time.png b/en/developer-docs/docs/assets/img/monitoring-and-insights/work-with-choreo-insights-api/update-token-expirary-time.png similarity index 100% rename from en/docs/assets/img/monitoring-and-insights/work-with-choreo-insights-api/update-token-expirary-time.png rename to en/developer-docs/docs/assets/img/monitoring-and-insights/work-with-choreo-insights-api/update-token-expirary-time.png diff --git a/en/docs/assets/img/platform-services/kafka-service-overview.png b/en/developer-docs/docs/assets/img/platform-services/kafka-service-overview.png similarity index 100% rename from en/docs/assets/img/platform-services/kafka-service-overview.png rename to en/developer-docs/docs/assets/img/platform-services/kafka-service-overview.png diff --git a/en/docs/assets/img/platform-services/set-ca-certificate.png b/en/developer-docs/docs/assets/img/platform-services/set-ca-certificate.png similarity index 100% rename from en/docs/assets/img/platform-services/set-ca-certificate.png rename to en/developer-docs/docs/assets/img/platform-services/set-ca-certificate.png diff --git a/en/docs/assets/img/platform-services/set-environment-variables.png b/en/developer-docs/docs/assets/img/platform-services/set-environment-variables.png similarity index 100% rename from en/docs/assets/img/platform-services/set-environment-variables.png rename to en/developer-docs/docs/assets/img/platform-services/set-environment-variables.png diff --git a/en/docs/assets/img/quick-start-guides/api-proxy-response.png b/en/developer-docs/docs/assets/img/quick-start-guides/api-proxy-response.png similarity index 100% rename from en/docs/assets/img/quick-start-guides/api-proxy-response.png rename to en/developer-docs/docs/assets/img/quick-start-guides/api-proxy-response.png diff --git a/en/docs/assets/img/quick-start-guides/create-choreo-organization.png b/en/developer-docs/docs/assets/img/quick-start-guides/create-choreo-organization.png similarity index 100% rename from en/docs/assets/img/quick-start-guides/create-choreo-organization.png rename to en/developer-docs/docs/assets/img/quick-start-guides/create-choreo-organization.png diff --git a/en/docs/assets/img/quick-start-guides/front-end-application.png b/en/developer-docs/docs/assets/img/quick-start-guides/front-end-application.png similarity index 100% rename from en/docs/assets/img/quick-start-guides/front-end-application.png rename to en/developer-docs/docs/assets/img/quick-start-guides/front-end-application.png diff --git a/en/docs/assets/img/quick-start-guides/web-application.png b/en/developer-docs/docs/assets/img/quick-start-guides/web-application.png similarity index 100% rename from en/docs/assets/img/quick-start-guides/web-application.png rename to en/developer-docs/docs/assets/img/quick-start-guides/web-application.png diff --git a/en/docs/assets/img/testing/graphql-console-org.png b/en/developer-docs/docs/assets/img/testing/graphql-console-org.png similarity index 100% rename from en/docs/assets/img/testing/graphql-console-org.png rename to en/developer-docs/docs/assets/img/testing/graphql-console-org.png diff --git a/en/docs/assets/img/testing/graphql-console.png b/en/developer-docs/docs/assets/img/testing/graphql-console.png similarity index 100% rename from en/docs/assets/img/testing/graphql-console.png rename to en/developer-docs/docs/assets/img/testing/graphql-console.png diff --git a/en/docs/assets/img/testing/openapi-console-org.png b/en/developer-docs/docs/assets/img/testing/openapi-console-org.png similarity index 100% rename from en/docs/assets/img/testing/openapi-console-org.png rename to en/developer-docs/docs/assets/img/testing/openapi-console-org.png diff --git a/en/docs/assets/img/testing/openapi-console.png b/en/developer-docs/docs/assets/img/testing/openapi-console.png similarity index 100% rename from en/docs/assets/img/testing/openapi-console.png rename to en/developer-docs/docs/assets/img/testing/openapi-console.png diff --git a/en/docs/assets/img/testing/websocket-console.png b/en/developer-docs/docs/assets/img/testing/websocket-console.png similarity index 100% rename from en/docs/assets/img/testing/websocket-console.png rename to en/developer-docs/docs/assets/img/testing/websocket-console.png diff --git a/en/docs/assets/img/tutorials/api-proxy-response.png b/en/developer-docs/docs/assets/img/tutorials/api-proxy-response.png similarity index 100% rename from en/docs/assets/img/tutorials/api-proxy-response.png rename to en/developer-docs/docs/assets/img/tutorials/api-proxy-response.png diff --git a/en/docs/assets/img/tutorials/role-based-auth/access-token.png b/en/developer-docs/docs/assets/img/tutorials/role-based-auth/access-token.png similarity index 100% rename from en/docs/assets/img/tutorials/role-based-auth/access-token.png rename to en/developer-docs/docs/assets/img/tutorials/role-based-auth/access-token.png diff --git a/en/docs/assets/img/tutorials/role-based-auth/api-resources.png b/en/developer-docs/docs/assets/img/tutorials/role-based-auth/api-resources.png similarity index 100% rename from en/docs/assets/img/tutorials/role-based-auth/api-resources.png rename to en/developer-docs/docs/assets/img/tutorials/role-based-auth/api-resources.png diff --git a/en/docs/assets/img/tutorials/role-based-auth/authorize-endpoint.png b/en/developer-docs/docs/assets/img/tutorials/role-based-auth/authorize-endpoint.png similarity index 100% rename from en/docs/assets/img/tutorials/role-based-auth/authorize-endpoint.png rename to en/developer-docs/docs/assets/img/tutorials/role-based-auth/authorize-endpoint.png diff --git a/en/docs/assets/img/tutorials/role-based-auth/callback-url.png b/en/developer-docs/docs/assets/img/tutorials/role-based-auth/callback-url.png similarity index 100% rename from en/docs/assets/img/tutorials/role-based-auth/callback-url.png rename to en/developer-docs/docs/assets/img/tutorials/role-based-auth/callback-url.png diff --git a/en/docs/assets/img/tutorials/role-based-auth/code.png b/en/developer-docs/docs/assets/img/tutorials/role-based-auth/code.png similarity index 100% rename from en/docs/assets/img/tutorials/role-based-auth/code.png rename to en/developer-docs/docs/assets/img/tutorials/role-based-auth/code.png diff --git a/en/docs/assets/img/tutorials/role-based-auth/consent.png b/en/developer-docs/docs/assets/img/tutorials/role-based-auth/consent.png similarity index 100% rename from en/docs/assets/img/tutorials/role-based-auth/consent.png rename to en/developer-docs/docs/assets/img/tutorials/role-based-auth/consent.png diff --git a/en/docs/assets/img/tutorials/role-based-auth/consumer-key.png b/en/developer-docs/docs/assets/img/tutorials/role-based-auth/consumer-key.png similarity index 100% rename from en/docs/assets/img/tutorials/role-based-auth/consumer-key.png rename to en/developer-docs/docs/assets/img/tutorials/role-based-auth/consumer-key.png diff --git a/en/docs/assets/img/tutorials/role-based-auth/enable-asgardeo-key-manager.png b/en/developer-docs/docs/assets/img/tutorials/role-based-auth/enable-asgardeo-key-manager.png similarity index 100% rename from en/docs/assets/img/tutorials/role-based-auth/enable-asgardeo-key-manager.png rename to en/developer-docs/docs/assets/img/tutorials/role-based-auth/enable-asgardeo-key-manager.png diff --git a/en/docs/assets/img/tutorials/role-based-auth/manage-permission.png b/en/developer-docs/docs/assets/img/tutorials/role-based-auth/manage-permission.png similarity index 100% rename from en/docs/assets/img/tutorials/role-based-auth/manage-permission.png rename to en/developer-docs/docs/assets/img/tutorials/role-based-auth/manage-permission.png diff --git a/en/docs/assets/img/tutorials/role-based-auth/permission-values.png b/en/developer-docs/docs/assets/img/tutorials/role-based-auth/permission-values.png similarity index 100% rename from en/docs/assets/img/tutorials/role-based-auth/permission-values.png rename to en/developer-docs/docs/assets/img/tutorials/role-based-auth/permission-values.png diff --git a/en/docs/assets/img/tutorials/role-based-auth/resource-permission.png b/en/developer-docs/docs/assets/img/tutorials/role-based-auth/resource-permission.png similarity index 100% rename from en/docs/assets/img/tutorials/role-based-auth/resource-permission.png rename to en/developer-docs/docs/assets/img/tutorials/role-based-auth/resource-permission.png diff --git a/en/docs/assets/img/tutorials/role-based-auth/scope-validation-failed.png b/en/developer-docs/docs/assets/img/tutorials/role-based-auth/scope-validation-failed.png similarity index 100% rename from en/docs/assets/img/tutorials/role-based-auth/scope-validation-failed.png rename to en/developer-docs/docs/assets/img/tutorials/role-based-auth/scope-validation-failed.png diff --git a/en/docs/assets/img/tutorials/role-based-auth/scopes.png b/en/developer-docs/docs/assets/img/tutorials/role-based-auth/scopes.png similarity index 100% rename from en/docs/assets/img/tutorials/role-based-auth/scopes.png rename to en/developer-docs/docs/assets/img/tutorials/role-based-auth/scopes.png diff --git a/en/docs/assets/img/tutorials/role-based-auth/sign-in-kim.png b/en/developer-docs/docs/assets/img/tutorials/role-based-auth/sign-in-kim.png similarity index 100% rename from en/docs/assets/img/tutorials/role-based-auth/sign-in-kim.png rename to en/developer-docs/docs/assets/img/tutorials/role-based-auth/sign-in-kim.png diff --git a/en/docs/assets/img/tutorials/role-based-auth/sign-in.png b/en/developer-docs/docs/assets/img/tutorials/role-based-auth/sign-in.png similarity index 100% rename from en/docs/assets/img/tutorials/role-based-auth/sign-in.png rename to en/developer-docs/docs/assets/img/tutorials/role-based-auth/sign-in.png diff --git a/en/docs/assets/img/tutorials/role-based-auth/token-endpoint.png b/en/developer-docs/docs/assets/img/tutorials/role-based-auth/token-endpoint.png similarity index 100% rename from en/docs/assets/img/tutorials/role-based-auth/token-endpoint.png rename to en/developer-docs/docs/assets/img/tutorials/role-based-auth/token-endpoint.png diff --git a/en/docs/assets/js/choreotheme.js b/en/developer-docs/docs/assets/js/choreotheme.js similarity index 100% rename from en/docs/assets/js/choreotheme.js rename to en/developer-docs/docs/assets/js/choreotheme.js diff --git a/en/docs/assets/js/prism-ballerina.js b/en/developer-docs/docs/assets/js/prism-ballerina.js similarity index 100% rename from en/docs/assets/js/prism-ballerina.js rename to en/developer-docs/docs/assets/js/prism-ballerina.js diff --git a/en/docs/assets/js/theme.js b/en/developer-docs/docs/assets/js/theme.js similarity index 100% rename from en/docs/assets/js/theme.js rename to en/developer-docs/docs/assets/js/theme.js diff --git a/en/docs/assets/lib/backtotop/img/cd-top-arrow.svg b/en/developer-docs/docs/assets/lib/backtotop/img/cd-top-arrow.svg similarity index 100% rename from en/docs/assets/lib/backtotop/img/cd-top-arrow.svg rename to en/developer-docs/docs/assets/lib/backtotop/img/cd-top-arrow.svg diff --git a/en/docs/assets/lib/backtotop/js/main.js b/en/developer-docs/docs/assets/lib/backtotop/js/main.js similarity index 100% rename from en/docs/assets/lib/backtotop/js/main.js rename to en/developer-docs/docs/assets/lib/backtotop/js/main.js diff --git a/en/docs/assets/lib/backtotop/js/util.js b/en/developer-docs/docs/assets/lib/backtotop/js/util.js similarity index 100% rename from en/docs/assets/lib/backtotop/js/util.js rename to en/developer-docs/docs/assets/lib/backtotop/js/util.js diff --git a/en/docs/assets/lib/highlightjs/ballerina.min.js b/en/developer-docs/docs/assets/lib/highlightjs/ballerina.min.js similarity index 100% rename from en/docs/assets/lib/highlightjs/ballerina.min.js rename to en/developer-docs/docs/assets/lib/highlightjs/ballerina.min.js diff --git a/en/docs/assets/lib/highlightjs/default.min.css b/en/developer-docs/docs/assets/lib/highlightjs/default.min.css similarity index 100% rename from en/docs/assets/lib/highlightjs/default.min.css rename to en/developer-docs/docs/assets/lib/highlightjs/default.min.css diff --git a/en/docs/assets/lib/highlightjs/highlight.min.js b/en/developer-docs/docs/assets/lib/highlightjs/highlight.min.js similarity index 100% rename from en/docs/assets/lib/highlightjs/highlight.min.js rename to en/developer-docs/docs/assets/lib/highlightjs/highlight.min.js diff --git a/en/docs/assets/lib/json-formatter/json-formatter.css b/en/developer-docs/docs/assets/lib/json-formatter/json-formatter.css similarity index 100% rename from en/docs/assets/lib/json-formatter/json-formatter.css rename to en/developer-docs/docs/assets/lib/json-formatter/json-formatter.css diff --git a/en/docs/assets/lib/json-formatter/json-formatter.umd.js b/en/developer-docs/docs/assets/lib/json-formatter/json-formatter.umd.js similarity index 100% rename from en/docs/assets/lib/json-formatter/json-formatter.umd.js rename to en/developer-docs/docs/assets/lib/json-formatter/json-formatter.umd.js diff --git a/en/docs/assets/lib/prism/prism.js b/en/developer-docs/docs/assets/lib/prism/prism.js similarity index 100% rename from en/docs/assets/lib/prism/prism.js rename to en/developer-docs/docs/assets/lib/prism/prism.js diff --git a/en/docs/authentication-and-authorization/configure-mutual-tls-between-components.md b/en/developer-docs/docs/authentication-and-authorization/configure-mutual-tls-between-components.md similarity index 100% rename from en/docs/authentication-and-authorization/configure-mutual-tls-between-components.md rename to en/developer-docs/docs/authentication-and-authorization/configure-mutual-tls-between-components.md diff --git a/en/docs/authentication-and-authorization/pass-end-user-attributes-to-upstream-services.md b/en/developer-docs/docs/authentication-and-authorization/pass-end-user-attributes-to-upstream-services.md similarity index 100% rename from en/docs/authentication-and-authorization/pass-end-user-attributes-to-upstream-services.md rename to en/developer-docs/docs/authentication-and-authorization/pass-end-user-attributes-to-upstream-services.md diff --git a/en/docs/authentication-and-authorization/secure-api-access-with-asgardeo.md b/en/developer-docs/docs/authentication-and-authorization/secure-api-access-with-asgardeo.md similarity index 100% rename from en/docs/authentication-and-authorization/secure-api-access-with-asgardeo.md rename to en/developer-docs/docs/authentication-and-authorization/secure-api-access-with-asgardeo.md diff --git a/en/docs/authentication-and-authorization/secure-api-access-with-azure-ad.md b/en/developer-docs/docs/authentication-and-authorization/secure-api-access-with-azure-ad.md similarity index 100% rename from en/docs/authentication-and-authorization/secure-api-access-with-azure-ad.md rename to en/developer-docs/docs/authentication-and-authorization/secure-api-access-with-azure-ad.md diff --git a/en/docs/authentication-and-authorization/secure-communication-between-the-choreo-gateway-and-your-backend-with-mutual-tls.md b/en/developer-docs/docs/authentication-and-authorization/secure-communication-between-the-choreo-gateway-and-your-backend-with-mutual-tls.md similarity index 100% rename from en/docs/authentication-and-authorization/secure-communication-between-the-choreo-gateway-and-your-backend-with-mutual-tls.md rename to en/developer-docs/docs/authentication-and-authorization/secure-communication-between-the-choreo-gateway-and-your-backend-with-mutual-tls.md diff --git a/en/docs/authentication-and-authorization/secure-web-applications-with-managed-authentication.md b/en/developer-docs/docs/authentication-and-authorization/secure-web-applications-with-managed-authentication.md similarity index 100% rename from en/docs/authentication-and-authorization/secure-web-applications-with-managed-authentication.md rename to en/developer-docs/docs/authentication-and-authorization/secure-web-applications-with-managed-authentication.md diff --git a/en/docs/authentication-and-authorization/test-secure-api-access-with-choreo-built-in-security-token-service.md b/en/developer-docs/docs/authentication-and-authorization/test-secure-api-access-with-choreo-built-in-security-token-service.md similarity index 100% rename from en/docs/authentication-and-authorization/test-secure-api-access-with-choreo-built-in-security-token-service.md rename to en/developer-docs/docs/authentication-and-authorization/test-secure-api-access-with-choreo-built-in-security-token-service.md diff --git a/en/docs/choreo-cli/choreo-cli-overview.md b/en/developer-docs/docs/choreo-cli/choreo-cli-overview.md similarity index 95% rename from en/docs/choreo-cli/choreo-cli-overview.md rename to en/developer-docs/docs/choreo-cli/choreo-cli-overview.md index f7839b173..6ec5834d3 100644 --- a/en/docs/choreo-cli/choreo-cli-overview.md +++ b/en/developer-docs/docs/choreo-cli/choreo-cli-overview.md @@ -1,6 +1,6 @@ -# Choreo Command Line Interface (CLI) Overview +# Choreo Command-Line Interface (CLI) Overview -The Choreo Command Line Interface (CLI) is a command-line tool that helps you easily work with Choreo using commands. By utilizing commands, it significantly improves the development experience for Choreo users. This versatile tool simplifies different stages of the development process, making interactions more efficient and user-friendly. +The Choreo command-line interface (CLI) is a command-line tool that helps you easily work with Choreo using commands. By utilizing commands, it significantly improves the development experience for Choreo users. This versatile tool simplifies different stages of the development process, making interactions more efficient and user-friendly. Choreo serves as a comprehensive internal platform-as-a-service. The Choreo CLI serves as a pivotal tool aimed at enhancing its capabilities. With the Choreo CLI, you can leverage the following benefits: diff --git a/en/docs/choreo-cli/get-started-with-the-choreo-cli.md b/en/developer-docs/docs/choreo-cli/get-started-with-the-choreo-cli.md similarity index 100% rename from en/docs/choreo-cli/get-started-with-the-choreo-cli.md rename to en/developer-docs/docs/choreo-cli/get-started-with-the-choreo-cli.md diff --git a/en/docs/choreo-cli/manage-authentication-with-personal-access-tokens.md b/en/developer-docs/docs/choreo-cli/manage-authentication-with-personal-access-tokens.md similarity index 100% rename from en/docs/choreo-cli/manage-authentication-with-personal-access-tokens.md rename to en/developer-docs/docs/choreo-cli/manage-authentication-with-personal-access-tokens.md diff --git a/en/docs/choreo-concepts/choreo-marketplace.md b/en/developer-docs/docs/choreo-concepts/choreo-marketplace.md similarity index 100% rename from en/docs/choreo-concepts/choreo-marketplace.md rename to en/developer-docs/docs/choreo-concepts/choreo-marketplace.md diff --git a/en/docs/choreo-concepts/ci-cd.md b/en/developer-docs/docs/choreo-concepts/ci-cd.md similarity index 78% rename from en/docs/choreo-concepts/ci-cd.md rename to en/developer-docs/docs/choreo-concepts/ci-cd.md index 0aa6e1d61..869c5c8b1 100644 --- a/en/docs/choreo-concepts/ci-cd.md +++ b/en/developer-docs/docs/choreo-concepts/ci-cd.md @@ -1,17 +1,17 @@ # CI/CD -Choreo provides a streamlined continuous integration and continuous deployment(CI/CD) experience to deploy applications and services efficiently across multiple environments. +Choreo provides a streamlined continuous integration and continuous deployment (CI/CD) experience to deploy applications and services efficiently across multiple environments. Choreo creates environments for each project, where all components within the project share the environments. An environment is an isolated deployment area with restricted network and resource access. Services deployed in one environment cannot communicate with services deployed in another. -The Choreo cloud data plane provides two default environments (i.e., development and production). However, if you are in a private data plane organization, you can customize and create multiple environments based on your requirements. +The Choreo cloud data plane provides two default environments (i.e., development and production). However, if you are in a private data plane organization, you can customize and create multiple environments based on your requirements. Choreo adopts a *build once, deploy many* strategy to manage components across multiple environments. An application is built only once (i.e., per commit if automatic build on commit is enabled or based on the selected commit during a manual build). Then it is promoted to subsequent environments. This allows testing changes in lower, non-production environments like development before promoting the build to production. -Choreo injects configurations and secrets that you maintain at the environment level into components at runtime. This ensures a strict separation of environment-specific configurations from source code. Although configurations can vary across environments, the code and the built container remain unchanged. Configurations and secrets include: +Choreo injects configurations and secrets that you maintain at the environment level into components at runtime. This ensures a strict separation of environment-specific configurations from source code. Although configurations can vary across environments, the code and the built container remain unchanged. Configurations and secrets include: - - Resource credentials to a database, cache, or other backing services. - - Credentials to external cloud services such as Amazon S3 or external APIs. +- Resource credentials to a database, cache, or other backing services. +- Credentials to external cloud services such as Amazon S3 or external APIs. All configurations and secrets are encrypted at rest and in transit and stored in a secure vault. In a private data plane organization, you can store configurations and secrets in your infrastructure. @@ -22,7 +22,9 @@ Choreo auto-generates build pipelines that may slightly differ depending on the - Builds a container image either from the provided source code or from a given Dockerfile for a specific commit. - Runs security and vulnerability scans if applicable, depending on the component type. - Pushes the container image to a container registry. In the cloud data plane, Choreo pushes the image to a Choreo-managed registry. If it is a private data plane organization, Choreo pushes the image to a registry that you own. -- Updates service endpoints and API specifications from the provided repository if applicable. +- Updates service endpoints and API specifications from the provided repository if applicable. + +In addition to these steps, some buildpacks support integrating unit tests into the build pipeline. For more details, see [Integrate Unit Tests into the Build Pipeline](../develop-components/integrate-unit-tests-into-the-build-pipeline.md). ### Repeatable builds @@ -33,36 +35,37 @@ Choreo can replicate builds from an identical code version (Git commit). This me ### Trigger a build -On the **Build** page, click **Build Latest**. If necessary you have the option to select a particular commit and build an image. +On the **Build** page, click **Build Latest**. If necessary, you have the option to select a particular commit and build an image. + +!!! note + Admin and Choreo DevOps users can trigger builds using specific tags from the connected Git repository. However, this action bypasses the standard branch-based deployment process and should only be used for critical, time-sensitive scenarios, as it can disrupt deployment track integrity. -If you want to automatically trigger a build with each commit, you can enable **Auto Build on Commit**. +If you want to automatically trigger a build with each commit, you can enable **Auto Build on Commit**. ### Build logs You can view build logs for specific builds on the **Build** page. - + To view details of a specific build, click **View Details** corresponding to the build. ## Deployment -Once you build an image in Choreo, you can deploy it via the **Deploy** page. To deploy an image, you can follow one of the approaches given below: +Once you build an image in Choreo, you can deploy it via the **Deploy** page. To deploy an image, you can follow one of the approaches given below: -- Manually deploy: In the **Deploy** page, go to the **Set Up** card and click **Deploy**. - -- Automatically deploy on build: In the **Deploy** page, go to **Set Up** card and enable **Auto Deploy on Build**. This automatically initiates deployment upon the completion of an automatic build. +- **Manually deploy**: In the **Deploy** page, go to the **Set Up** card and click **Deploy**. +- **Automatically deploy on build**: In the **Deploy** page, go to the **Set Up** card and enable **Auto Deploy on Build**. This automatically initiates deployment upon the completion of an automatic build. !!! info - To enable **Auto Deploy on Build**, you must enable **Auto Build on Commit**. This is because automatic deployment is not necessary or useful in scenarios where automatic build is not enabled. + To enable **Auto Deploy on Build**, you must enable **Auto Build on Commit**. This is because automatic deployment is not necessary or useful in scenarios where automatic build is not enabled. !!! note - You must trigger the first build in a Ballerina component manually to ensure that Choreo applies the required configurations to the development environment. You can enable automatic builds subsequently. - Choreo automatically checks the configurable defined in your source code against the configurable values applied in an environment. Choreo requests the configurable values on deployment and promotion. If you have changed the configurables in your Ballerina component, auto-build pipelines can fail as a precaution to avoid a component crash at runtime due to missing configurables. - The configurable verifying capability is only available for Ballerina components. For Dockerfile-based components, ensure to manage and update the configurations and secrets in environments ahead of time. You must also ensure backward compatibility between at least one release if you change the configurations. - ### Set up area and initial deployment -In the deploy phase, Choreo uses a setup area to merge the Docker image with its environment-independent configurations. Choreo then deploys this composite to the environment. This is known as the initial deployment. +In the deploy phase, Choreo uses a setup area to merge the Docker image with its environment-independent configurations. Choreo then deploys this composite to the environment. This is known as the initial deployment. ### Immutable deployments @@ -70,7 +73,7 @@ Once Choreo deploys a component with configurations, the configurations become i ### Promote a component to a higher environment -Choreo builds a container once per GitHub commit and then promotes it to subsequent higher environments. +Choreo builds a container once per GitHub commit and then promotes it to subsequent higher environments. You can go to the **Deploy** page of a component and promote it manually across environments. @@ -80,13 +83,13 @@ Choreo allows you to define both environment-independent configurations and envi ### Environment-independent configurations -These configurations apply to all environments. +These configurations apply to all environments. To change environment-independent configurations, go to the **Deploy** page of the component, make the necessary configuration changes via the **Set Up** card, and then trigger a new deployment to the initial environment. From there, you can proceed to promote the component to higher environments. ### Environment-specific configurations -These configurations apply to a particular environment. +These configurations apply to a particular environment. To change environment-specific configurations, go to the **Deploy** page of the component, make the necessary configuration changes via the specific environment card, and trigger a new deployment. @@ -96,15 +99,14 @@ To learn more about managing these configurations, see [Configuration Management The information on the **Execute** page is only applicable to scheduled and manual task components. -To track and monitor executions associated with a deployed scheduled task or manual task, go to the left navigation menu and click **Execute**. +To track and monitor executions associated with a deployed scheduled task or manual task, go to the left navigation menu and click **Execute**. You can view current and historic execution details along with a quick snapshot of recent activity via the total count of executions within the last 30 days. For each execution, you can view vital details such as the unique execution ID, the time it was triggered, and relevant revision information. Furthermore, you can dive deeper into the details by clicking on a specific execution to access its associated logs. This information enhances transparency, troubleshooting capabilities, and overall execution management, allowing you to easily monitor and analyze workflows. - ## Zero-downtime deployments Choreo performs rolling updates to ensure zero downtime between deployments and promotions. -A new build undergoes a health check before traffic is switched to it from the current build. +A new build undergoes a health check before traffic is switched to it from the current build. If you configure the necessary health checks for a component, it can prevent deploying and promoting unhealthy versions of a component. diff --git a/en/docs/choreo-concepts/component.md b/en/developer-docs/docs/choreo-concepts/component.md similarity index 100% rename from en/docs/choreo-concepts/component.md rename to en/developer-docs/docs/choreo-concepts/component.md diff --git a/en/docs/choreo-concepts/connections.md b/en/developer-docs/docs/choreo-concepts/connections.md similarity index 100% rename from en/docs/choreo-concepts/connections.md rename to en/developer-docs/docs/choreo-concepts/connections.md diff --git a/en/docs/choreo-concepts/data-planes.md b/en/developer-docs/docs/choreo-concepts/data-planes.md similarity index 100% rename from en/docs/choreo-concepts/data-planes.md rename to en/developer-docs/docs/choreo-concepts/data-planes.md diff --git a/en/docs/choreo-concepts/deployment-tracks.md b/en/developer-docs/docs/choreo-concepts/deployment-tracks.md similarity index 100% rename from en/docs/choreo-concepts/deployment-tracks.md rename to en/developer-docs/docs/choreo-concepts/deployment-tracks.md diff --git a/en/docs/choreo-concepts/endpoint.md b/en/developer-docs/docs/choreo-concepts/endpoint.md similarity index 100% rename from en/docs/choreo-concepts/endpoint.md rename to en/developer-docs/docs/choreo-concepts/endpoint.md diff --git a/en/docs/choreo-concepts/environments.md b/en/developer-docs/docs/choreo-concepts/environments.md similarity index 100% rename from en/docs/choreo-concepts/environments.md rename to en/developer-docs/docs/choreo-concepts/environments.md diff --git a/en/docs/choreo-concepts/organization.md b/en/developer-docs/docs/choreo-concepts/organization.md similarity index 100% rename from en/docs/choreo-concepts/organization.md rename to en/developer-docs/docs/choreo-concepts/organization.md diff --git a/en/docs/choreo-concepts/project.md b/en/developer-docs/docs/choreo-concepts/project.md similarity index 100% rename from en/docs/choreo-concepts/project.md rename to en/developer-docs/docs/choreo-concepts/project.md diff --git a/en/developer-docs/docs/choreo-concepts/resource-hierarchy.md b/en/developer-docs/docs/choreo-concepts/resource-hierarchy.md new file mode 100644 index 000000000..b3b535a55 --- /dev/null +++ b/en/developer-docs/docs/choreo-concepts/resource-hierarchy.md @@ -0,0 +1,25 @@ +# Resource Hierarchy + + +The following diagram depicts the high-level resources and their relationships in Choreo. + +![Resource hierarchy](../assets/img/choreo-concepts/resource-hierarchy.png){.cInlineImage-full} + +## Organizations and data planes + +Data planes are connected to the organization and are available for all projects within the organization. When you create an environment in a project, the data plane connected to the organization is linked with an automatically generated Kubernetes namespace. + +## Environments and data planes + +Choreo allows multiple Kubernetes clusters to be associated with an environment. This enables you to build highly resilient and resource-efficient solutions that utilize multiple clusters. Choreo synchronizes your applications and workloads between associated clusters in an environment, allowing you to perform multi-cluster deployment with a single click. + +The following diagram illustrates how multiple clusters associate with different environments: + +![Environments and dataplanes](../assets/img/choreo-concepts/environments-and-dataplanes.png){.cInlineImage-full} + +!!! info "Note" + It is not necessary to use a different cluster per environment. You can create multiple environments on the same cluster. The above diagram is an example of a specific solution. Your application architecture may require a different configuration than what is depicted. + +## Components and environments + +Components belong to a project in Choreo, and environments are provisioned per project. When a component is deployed, it is deployed as a container to the specified environment. Once deployed, you can promote the container image across the environments available in the project. \ No newline at end of file diff --git a/en/docs/choreo-samples/explore-the-demo-organization.md b/en/developer-docs/docs/choreo-samples/explore-the-demo-organization.md similarity index 52% rename from en/docs/choreo-samples/explore-the-demo-organization.md rename to en/developer-docs/docs/choreo-samples/explore-the-demo-organization.md index a80524a14..5599e9edd 100644 --- a/en/docs/choreo-samples/explore-the-demo-organization.md +++ b/en/developer-docs/docs/choreo-samples/explore-the-demo-organization.md @@ -1,12 +1,12 @@ # Explore the Demo Organization -The demo organization in Choreo provides a hands-on view of a fully deployed system in a read-only mode. This organization is maintained by Choreo and demonstrates a real-world use case to help you understand how Choreo simplifies developing, deploying, and managing cloud native applications. +The demo organization in Choreo provides a hands-on view of a fully deployed system in read-only mode. This organization, maintained by Choreo, demonstrates a real-world use case to help you understand how Choreo simplifies developing, deploying, and managing cloud-native applications. ## Prerequisites - If you are signing in to the Choreo Console for the first time, create an organization as follows: 1. Go to the [Choreo Console](https://console.choreo.dev/) and sign in using Google, GitHub, or Microsoft. - 2. Enter a unique organization name, for example, `Stark Industries`. + 2. Enter a unique organization name. For example, `Stark Industries`. 3. Read and accept the privacy policy and terms of use. 4. Click **Create**. This creates the organization and opens the organization home page. @@ -15,7 +15,7 @@ The demo organization in Choreo provides a hands-on view of a fully deployed sys 1. Sign in to the [Choreo Console](https://console.choreo.dev/). 2. In the Choreo Console header, click the **Organization** list to view available organizations. 3. Under **Invited Organizations**, you will see the **Demo Organization**. -4. To gain access to the **Demo Organization**, click **Join** corresponding to it. +4. To gain access to the **Demo Organization**, click **Join** next to it. ## Demo organization overview @@ -23,13 +23,9 @@ When you join the demo organization, you gain access to a comprehensive, read-on Key aspects you can explore include: - - Projects and components: Take a look at the sample projects and their respective components, where each component serves a distinct function within the customer rewards management system. +- **Projects and components**: View the sample projects and their respective components, where each component serves a distinct function within the customer rewards management system. +- **Component details and architecture**: Understand the architecture by exploring how each component is configured, including environment variables, API keys, and other dependencies that enable the required functionality. +- **Build and deployment pipelines**: Inspect the build configurations and deployment history for each component. +- **Delivery insights, usage insights, and observability metrics**: Analyze metrics and insights for each component. - - Component details and architecture: Understand the architecture by exploring how each component is configured, including environment variables, API keys, and other dependencies that enable the required functionality. - - - Build and deployment pipelines: Inspect the build configurations and deployment history for each component. - - - Delivery insights, usage insights, and observability metrics for each component. - -For more details on the architecture and source code, see the [Customer reward management system sample](https://github.com/wso2/choreo-samples/tree/main/customer-reward-management#readme) on GitHub. This repository provides comprehensive documentation on the project setup, and its code structure, enabling you to replicate or modify it as needed. - +For more details on the architecture and source code, see the [Customer Reward Management System Sample](https://github.com/wso2/choreo-samples/tree/main/customer-reward-management#readme) on GitHub. This repository provides comprehensive documentation on the project setup and its code structure, enabling you to replicate or modify it as needed. diff --git a/en/developer-docs/docs/choreo-samples/quick-deploy-a-sample.md b/en/developer-docs/docs/choreo-samples/quick-deploy-a-sample.md new file mode 100644 index 000000000..55c7c103e --- /dev/null +++ b/en/developer-docs/docs/choreo-samples/quick-deploy-a-sample.md @@ -0,0 +1,36 @@ +# Quick Deploy a Sample + +Choreo provides a **Quick Deploy** option for samples, allowing you to deploy a sample with a single click. This feature enables you to quickly explore and experiment with the sample. + +## Prerequisites + +Before you start using the samples, complete the following steps: + +- If you're signing in to Choreo for the first time, follow these steps to create an organization and project: + 1. Go to [https://console.choreo.dev/](https://console.choreo.dev/) and sign in using your preferred method. + 2. Enter a unique organization name. For example, `Stark Industries`. + 3. Read and accept the privacy policy and terms of use. + 4. Click **Create**. This creates the organization and takes you to its **Overview** page. + 5. On the organization home page, click **+ Create Project**. + 6. Enter a display name, unique name, and description for the project. + 7. Click **Create**. This creates the project and takes you to its **Overview** page. + +## Try out quick deploy + +To quickly deploy a sample, follow these steps: + +1. Sign in to the [Choreo Console](https://console.choreo.dev/). +2. On the Choreo Console header, go to the **Project** list and select your project. This opens the project **Overview** page. +3. On the project **Overview** page, go to the **Create from a Sample** section. You will see a selection of samples. +4. To view the complete collection of samples, click **View All Samples**. +5. Hover over a sample of your choice and click **Quick Deploy**. This creates the component and deploys it automatically. + +## Post-deployment actions + +Once you quick deploy a sample, follow one of the post-deployment actions below based on the component type: + +- **For services**: Go to the **Test Console** to test the deployed service. +- **For web applications**: Open the deployed web application using the provided URL. +- **For manual tasks and scheduled tasks**: Go to the **Execute** page and run the task. For scheduled tasks, you can also find the cron schedule on the **Overview** page. + +This feature allows you to quickly explore and understand how Choreo works with minimal setup. diff --git a/en/developer-docs/docs/choreo-samples/samples-overview.md b/en/developer-docs/docs/choreo-samples/samples-overview.md new file mode 100644 index 000000000..6b3198203 --- /dev/null +++ b/en/developer-docs/docs/choreo-samples/samples-overview.md @@ -0,0 +1,36 @@ +# Samples Overview + +Choreo provides an extensive collection of samples for a wide range of use cases. You can quickly deploy and explore these samples to easily understand the core functionalities of the platform. + +## Prerequisites + +Before you use the samples, complete the following steps: + +- If you're signing in for the first time, follow these steps to create an organization and then create a project: + + 1. Go to the [Choreo Console](https://console.choreo.dev/) and sign in using Google, GitHub, or Microsoft. + 2. Enter a unique organization name. For example, `Stark Industries`. + 3. Read and accept the privacy policy and terms of use. + 4. Click **Create**. This creates an organization and takes you to its **Overview** page. + 5. On the organization home page, click **+ Create Project**. + 6. Enter a display name, unique name, and description for the project. + 7. Click **Create**. This creates the project and takes you to its **Overview** page. + +## Explore the Choreo samples collection + +You can filter and explore Choreo's sample collection based on your preference. + +To view available samples, follow these steps: + +1. Sign in to the [Choreo Console](https://console.choreo.dev/). +2. In the Choreo Console header, go to the **Project** list and select your project to open its **Overview** page. +3. On the project **Overview** page, go to the **Create from a Sample** section. You will see a selection of samples. +4. To see the complete collection of samples, click **View All Samples**. + +When you view all samples, you can filter and search for samples by the following criteria: + +- **Buildpack**: Filters by the technology used. For example, Ballerina, NodeJS, Docker, etc. +- **Component Type**: Filters by the component type. For example, service, web application, scheduled tasks, manual tasks, etc. +- **Tags**: Use tags like REST, HTTP, or GraphQL to find samples with specific functionalities or integrations. + +You can either quick deploy a sample or access its source code on GitHub. For details on quick deploying a sample, see [Quick Deploy a Sample](./quick-deploy-a-sample.md). diff --git a/en/developer-docs/docs/consuming-services/consume-an-api-key-secured-service.md b/en/developer-docs/docs/consuming-services/consume-an-api-key-secured-service.md new file mode 100644 index 000000000..3d7f5c684 --- /dev/null +++ b/en/developer-docs/docs/consuming-services/consume-an-api-key-secured-service.md @@ -0,0 +1,49 @@ +# Consume an API Key Secured Service + +{% include "discovering-an-api-devportal.md" %} + +## Creating an API Key + +To consume an API secured with an API Key, an API Key is required. To obtain an API Key, an application must first be created in the Choreo Developer Portal. This application represents a physical entity (such as a mobile app, web app, or device) and serves as the means to subscribe to APIs under a defined usage policy. The API Key is associated with a specific application, and an application can be created during the API Key generation process if needed. + +--- + +### Steps to Create an API Key + +1. Navigate to the [Choreo Developer Portal](https://devportal.choreo.dev) and sign in. +2. Click on **APIs** in the Developer Portal header. +3. Select the desired API that requires an API Key for access. +4. This will take you to the API overview page, where you can manage credentials. + +#### Generating Environment-Specific API Keys. + +Choreo allows you to generate API keys for production and sandbox environments. + +!!! note + Access to production endpoints may be restricted based on your user role. Ensure you have the required permissions before generating production keys. + +Follow these steps to generate an API Key: + +1. In the left navigation menu, select the desired environment under **Credentials**. The **API Keys** pane for the chosen environment will open. +2. If any API keys already exist, they will be listed here. +3. Click **Generate API Key** and configure the following options: + - **Key Name**: Provide a suitable name for the API key. + - **Application**: Select an existing application or create a new one. + - **Subscription Policy**: Choose an appropriate subscription policy. +4. Click **Generate**. The newly created API Key will be displayed. + + +!!! note + If the selected application is already subscribed to the chosen API, the subscription selection step will be skipped. + If the selected API has multiple endpoints, an endpoint needs to be selected during API key generation. + +## Consume an API + +Use this API Key to authenticate API requests by including it in the `api-key` header when invoking the API. + +Example: +```bash +curl -H "api-key: " -X GET "https://my-sample-api.choreoapis.dev/greet" +``` + +For managing API keys, see [Manage API Keys](./manage-api-keys.md) \ No newline at end of file diff --git a/en/developer-docs/docs/consuming-services/consume-an-oauth2-secured-service.md b/en/developer-docs/docs/consuming-services/consume-an-oauth2-secured-service.md new file mode 100644 index 000000000..c91d8fe72 --- /dev/null +++ b/en/developer-docs/docs/consuming-services/consume-an-oauth2-secured-service.md @@ -0,0 +1,57 @@ +# Consume an OAuth2 Secured Service + +{% include "discovering-an-api-devportal.md" %} + +## Create an application + +{% include "create-an-application.md" %} + +## Subscribe to an API + +{% include "create-a-subscription.md" %} + +## Generate an access token via curl + +Follow these steps to generate an access token for your application using cURL: + +1. In the [Choreo Developer Portal](https://devportal.choreo.dev) header, click **Applications**. + +2. On the **My Applications** page, click on the application for which you want to generate the token. + +3. In the left navigation menu, click the desired environment under **Credentials**. This opens the **Application Keys** pane for that environment. + +4. Copy the **Consumer key**, **Consumer secret**, and **Token endpoint** values. + +5. Use the following template and replace the placeholders with the values you copied: + + === "Format" + ```bash + curl -k -X POST -d "grant_type=client_credentials" -H "Authorization: Basic " + ``` + +6. Run the curl command to generate an access token. + +## Generate an access token via the Developer Portal UI (for testing) + +To generate an access token for **testing purposes**, follow these steps: + +1. In the [Choreo Developer Portal](https://devportal.choreo.dev) header, click **Applications**. + +2. On the **My Applications** page, click on the application for which you want to generate keys and tokens. + +3. In the left navigation menu, click the desired environment under **Credentials**. This opens the **Application Keys** pane for that environment. + +4. Click **Generate Token** to create a test access token. + +## Consume an API + +Use this generated access token to authenticate API requests by including it in the `Bearer` header when invoking the API. + +Example: + +```bash +curl -H "Authorization: Bearer " -X GET "https://my-sample-api.choreoapis.dev/greet" +``` + +!!! note + The name of the Authorization header may vary depending on the API provider’s configuration. Always refer to the API’s Swagger (OpenAPI) definition for the correct header format. diff --git a/en/developer-docs/docs/consuming-services/consuming-a-service-apikey.md b/en/developer-docs/docs/consuming-services/consuming-a-service-apikey.md new file mode 100644 index 000000000..4bc417bd2 --- /dev/null +++ b/en/developer-docs/docs/consuming-services/consuming-a-service-apikey.md @@ -0,0 +1,82 @@ +# Consume an API Key Secured Service + +## Overview + +Choreo is a powerful platform that enables developers to create, deploy, and consume services efficiently. The Choreo Developer Portal simplifies API discovery and usage, allowing developers to integrate APIs seamlessly into their applications. + +This guide is intended for application developers (both internal and external) who wish to consume APIs published in the Developer Portal to build their applications. You will learn how to: + +- Discover APIs +- Create an application and generate credentials +- Subscribe to an API +- Consume a published REST API via a web application + +--- + +## Prerequisites + +Before proceeding, ensure you have access to a published service to consume. If you do not have one, follow the [Develop a Service](../develop-components/develop-services/develop-a-service.md) guide to create and deploy a sample REST API. + +--- + +## Discover APIs + +In the Choreo Developer Portal, developers can search for APIs by name. APIs and services created and published through the Choreo Console are visible in the Developer Portal based on their visibility settings: + +- **Public**: Visible to all users in the Developer Portal. +- **Private**: Accessible only to signed-in users. +- **Restricted**: Available to users with specific roles, enabling granular access control. + +For more details, refer to [Control API Visibility](../api-management/control-api-visibility.md). + +### Viewing Available APIs + +The Developer Portal lists APIs categorized by their major versions. The API overview page displays: + +- Subscribed versions of the API +- Subscription details (e.g., application name and creation date) + +![Developer Portal APIs](../assets/img/consume/developer-portal-apis.png) + +### Selecting the Correct API Version + +> **Tip:** It is recommended to use the latest version of an API. Copy the **Endpoint(s)** from the API overview page and integrate it into your client application to ensure compatibility with the most recent updates. + +--- + +## Creating an API Key + +To consume an API secured with an API Key, an API Key is required. To obtain an API Key, an application must first be created in the Choreo Developer Portal. This application represents a physical entity (such as a mobile app, web app, or device) and serves as the means to subscribe to APIs under a defined usage policy. The API Key is associated with a specific application, and an application can be created during the API Key generation process if needed. + +--- + +### Steps to Create an API Key + +1. Navigate to the [Choreo Developer Portal](https://devportal.choreo.dev) and sign in. +2. Click on **APIs** in the Developer Portal header. +3. Select the desired API that requires an API Key for access. +4. This will take you to the API overview page, where you can manage credentials. + +#### Generating Environment-Specific API Keys. + +Choreo allows you to generate API keys for production and non-production environments. + +!!! note + Access to production endpoints may be restricted based on your user role. Ensure you have the required permissions before generating production keys. + +Follow these steps to generate an API Key: + +1. In the left navigation menu, select the desired environment under **Credentials**. The **API Keys** pane for the chosen environment will open. +2. If any API keys already exist, they will be listed here. +3. Click **Generate API Key** and configure the following options: + - **Key Name**: Provide a suitable name for the API key. + - **Environment**: Choose an environment (if multiple environments are configured for the API). + - **Application**: Select an existing application or create a new one. + - **Subscription Policy**: Choose an appropriate subscription policy. +4. Click **Generate**. The newly created API Key will be displayed. + + +!!! note + If the selected application is already subscribed to the chosen API, the subscription selection step will be skipped. + +Use this API Key to authenticate API requests by including it in the `api-key` header when invoking the API. diff --git a/en/developer-docs/docs/consuming-services/create-a-subscription.md b/en/developer-docs/docs/consuming-services/create-a-subscription.md new file mode 100644 index 000000000..ec3622f00 --- /dev/null +++ b/en/developer-docs/docs/consuming-services/create-a-subscription.md @@ -0,0 +1,25 @@ + +To use a published API in your application, you must subscribe to it. When you subscribe to an API, your subscription covers all minor versions within the API's major version. + +The subscription process ensures secure authentication of API requests using application keys. While you can generate credentials for an API without subscribing to an application, this approach limits advanced configuration options such as access token expiry time, revoke token expiry time, ID token expiry time, and enabling access to the API without a secret. Generating keys directly in the API is suitable for testing or short-term use but is not recommended for long-term production usage. + +To subscribe to an API via an application, follow these steps: + +1. Go to the [Choreo Developer Portal](https://devportal.choreo.dev) and sign in. + +2. To navigate to applications, in the Developer Portal header, click **Applications**. + +3. On the **My Applications** page, click on the application you want to use to subscribe to an API. + +4. In the left navigation menu, click **Subscriptions**. + +5. In the **Subscription Management** pane, click **+ Add APIs**. + +6. Click **Add** to subscribe to an API. You can subscribe to one or more APIs based on your requirements. + + !!! tip + When a new minor version of an API is published, the major version-based invocation URL automatically routes to the latest minor version within the subscribed API's major version. This ensures that existing client applications continue to function without disruption while benefiting from improvements or additions in the newer minor version. + + ![Add APIs](../assets/img/consume/add-apis.png) + +Once you subscribe to an API, you can invoke it using the application keys. diff --git a/en/developer-docs/docs/consuming-services/create-an-application.md b/en/developer-docs/docs/consuming-services/create-an-application.md new file mode 100644 index 000000000..6918dd73b --- /dev/null +++ b/en/developer-docs/docs/consuming-services/create-an-application.md @@ -0,0 +1,54 @@ + +An application in Choreo is a logical representation of a physical application, such as a mobile app, web app, or device. To consume an API in Choreo, you need to create an application that maps to your physical application and subscribe to the required API under a usage policy plan. This plan provides a usage quota. A single application can have multiple API subscriptions. Using the consumer key and consumer secret, you can generate an access token to invoke all APIs subscribed to the same application. + +This guide walks you through the steps to create an application in Choreo. + +## Step 1: Create an application + +To create an application in the Choreo Developer Portal, follow these steps: + +1. Go to the [Choreo Developer Portal](https://devportal.choreo.dev) and sign in. + +2. In the Developer Portal header, click **Applications** and then click **+Create**. + +3. Enter application details. Provide a name and description for your application. + +4. Click **Create**. + +This creates the application and opens the **Application Overview** page. Here, you can view details such as the token type, workflow status, and the application owner. + +## Step 2: Generate keys + +Choreo uses OAuth 2.0 bearer token-based authentication for API access. An API access token is a string passed as an HTTP header in API requests to authenticate access. + +Once you create an application, you can generate credentials for it. Choreo provides a consumer key and consumer secret when you generate credentials for the first time. The consumer key acts as the unique identifier for the application and is used for authentication. + +### Generate environment-specific keys and tokens + +You can generate keys and tokens to invoke production and non-production endpoints separately. + +!!! info "Note" + Access to production endpoints depends on your role. If you have the necessary permissions, you can generate keys and tokens for production endpoints. + +1. In the [Choreo Developer Portal](https://devportal.choreo.dev) header, click **Applications**. + +2. On the **My Applications** page, click on the application for which you want to generate keys and tokens. + +3. In the left navigation menu, click the desired environment under **Credentials**. This opens the **Application Keys** pane for that environment. + +4. Expand **Advanced configurations** and review the following options: + - **Grant types**: Select the grant types to use when generating the access token. + - **Public client**: Enable **Allow authentication without the client secret** if your application is a public client (e.g., a browser or mobile app). + - **PKCE for enhanced security**: Set to **Mandatory** if you want the application to send a code challenge in the authorization request and a code verifier in the token request. Asgardeo supports SHA-256 and plain. + - **Application access token expiry time**: Set the access token expiry time in seconds. + - **Refresh token expiry time**: Set the refresh token expiry time in seconds. + - **ID token expiry time**: Set the ID token expiry time in seconds. + +5. Click **Generate Credentials**. The **Application Keys** pane will display the consumer key and consumer secret. + +You can use the consumer key and consumer secret to generate an API access token by invoking the token endpoint. You can also revoke the access token by invoking the revoke endpoint. + +To generate a test token for testing purposes, click **Generate Token** and copy the displayed token. Alternatively, click **cURL** to copy the generated cURL command and obtain a test token using a cURL client. + +!!! warning + Do not use the test token in your production environment. diff --git a/en/developer-docs/docs/consuming-services/discovering-an-api-devportal.md b/en/developer-docs/docs/consuming-services/discovering-an-api-devportal.md new file mode 100644 index 000000000..638b2a916 --- /dev/null +++ b/en/developer-docs/docs/consuming-services/discovering-an-api-devportal.md @@ -0,0 +1,41 @@ +Choreo is a powerful platform that enables developers to create, deploy, and consume services efficiently. The Choreo Developer Portal simplifies API discovery and usage, allowing developers to integrate APIs seamlessly into their applications. + +This guide is intended for application developers (both internal and external) who wish to consume APIs published in the Developer Portal to build their applications. You will learn how to: + +- Discover APIs +- Create an application and generate credentials +- Subscribe to an API +- Consume a published REST API via a web application + +--- + +## Prerequisites + +Before proceeding, ensure you have access to a published service to consume. If you do not have one, follow the [Develop a Service](../develop-components/develop-services/develop-a-service.md) guide to create and deploy a sample REST API. + +--- + +## Discover APIs + +In the Choreo Developer Portal, developers can search for APIs by name. APIs and services created and published through the Choreo Console are visible in the Developer Portal based on their visibility settings: + +- **Public**: Visible to all users in the Developer Portal. +- **Private**: Accessible only to signed-in users. +- **Restricted**: Available to users with specific roles, enabling granular access control. + +For more details, refer to [Control API Visibility](../api-management/control-api-visibility.md). + +### Viewing Available APIs + +The Developer Portal lists APIs categorized by their major versions. The API overview page displays: + +- Subscribed versions of the API +- Subscription details (e.g., application name and creation date) + +![Developer Portal APIs](../assets/img/consume/developer-portal-apis.png) + +### Selecting the Correct API Version + +> **Tip:** It is recommended to use the latest version of an API. Copy the **Endpoint(s)** from the API overview page and integrate it into your client application to ensure compatibility with the most recent updates. + +--- \ No newline at end of file diff --git a/en/developer-docs/docs/consuming-services/generate-an-access-token.md b/en/developer-docs/docs/consuming-services/generate-an-access-token.md new file mode 100644 index 000000000..edca1ac87 --- /dev/null +++ b/en/developer-docs/docs/consuming-services/generate-an-access-token.md @@ -0,0 +1,48 @@ +# Generate an Access Token + +Using access tokens for request authorization enhances security by preventing certain types of denial-of-service (DoS) attacks on published APIs. API consumers generate access tokens to access APIs, including them as string values in HTTP header requests. + +When you register an application in the Developer Portal, you can generate a consumer key and consumer secret. These credentials represent the application's identity. The consumer key acts as the unique identifier for the application, similar to a username, and is used to authenticate API requests. Choreo issues an access token for the application based on the consumer key. + +This guide walks you through the steps to generate an access token for your application in Choreo. + +## Prerequisites + +Before proceeding, ensure you have the following: + +1. An application in the [Choreo Developer Portal](https://devportal.choreo.dev). If you don’t have one, [create a new application](https://wso2.com/choreo/docs/consuming-services/manage-application/#step-1-create-an-application). +2. [Generate keys for the application](https://wso2.com/choreo/docs/consuming-services/create-an-application/#step-2-generate-keys). +3. [Subscribe APIs to the application](https://wso2.com/choreo/docs/consuming-services/create-a-subscription/#manage-subscriptions). + +## Generate an access token via curl + +Follow these steps to generate an access token for your application using cURL: + +1. In the [Choreo Developer Portal](https://devportal.choreo.dev) header, click **Applications**. + +2. On the **My Applications** page, click on the application for which you want to generate the token. + +3. In the left navigation menu, click the desired environment under **Credentials**. This opens the **Application Keys** pane for that environment. + +4. Copy the **Consumer key**, **Consumer secret**, and **Token endpoint** values. + +5. Use the following template and replace the placeholders with the values you copied: + + === "Format" + ```bash + curl -k -X POST -d "grant_type=client_credentials" -H "Authorization: Basic " + ``` + +6. Run the curl command to generate an access token. + +## Generate an access token via the Developer Portal UI (for testing) + +To generate an access token for **testing purposes**, follow these steps: + +1. In the [Choreo Developer Portal](https://devportal.choreo.dev) header, click **Applications**. + +2. On the **My Applications** page, click on the application for which you want to generate keys and tokens. + +3. In the left navigation menu, click the desired environment under **Credentials**. This opens the **Application Keys** pane for that environment. + +4. Click **Generate Token** to create a test access token. diff --git a/en/developer-docs/docs/consuming-services/manage-api-keys.md b/en/developer-docs/docs/consuming-services/manage-api-keys.md new file mode 100644 index 000000000..c8510d50f --- /dev/null +++ b/en/developer-docs/docs/consuming-services/manage-api-keys.md @@ -0,0 +1,21 @@ +# Manage API Keys + +To access a published API secured with an API Key, you need to generate a dedicated API Key for that specific API. This key acts as a unique identifier, enabling authorized usage while maintaining security and control over how the API is consumed. + +Once created, API Keys can be managed through two locations within the Choreo Developer Portal: + +- **Credentials section of the API**: This section provides an overview of all API Keys associated with the specific API, enabling API owners to monitor and manage access. +- **Credentials section of the Application**: This section allows application owners to view and manage all API Keys linked to their application, ensuring they have control over API subscriptions and access. + +From these sections, you can perform various API Key management actions, such as regenerating and deleting. + +## API Key Regeneration + +API Key regeneration allows you to obtain a new secret key for an existing API Key while ensuring minimal disruption to service. When an API Key is regenerated, a new secret key is generated, and the existing key remains valid for a grace period of one hour before being revoked. This ensures that applications have sufficient time to update their credentials without experiencing service interruptions. + +!!! warning + Ensure that all applications using the existing API Key are updated with the newly generated key within the grace period to prevent any disruptions in API invocations. + +## API Key Deletion + +API Keys can be deleted when they are no longer needed. Deleting an API Key immediately revokes its access, preventing further use of the key for API invocations. This action is irreversible and should be performed with caution, as any application relying on the deleted API Key will lose access to the API immediately. \ No newline at end of file diff --git a/en/developer-docs/docs/consuming-services/manage-application.md b/en/developer-docs/docs/consuming-services/manage-application.md new file mode 100644 index 000000000..21f868066 --- /dev/null +++ b/en/developer-docs/docs/consuming-services/manage-application.md @@ -0,0 +1,49 @@ +# Manage Applications + +{% include "create-an-application.md" %} + +## Grant types + +Choreo uses OAuth 2.0 for authentication. In OAuth 2.0, grant types are methods that allow client applications to obtain an access token. The type of grant used depends on the resource owner, the application type, and the trust relationship between the authorization server and the resource owner. + +### Authorization code grant + +The Authorization Code flow is a secure way for a client application to obtain an access token without exposing the user's credentials. The user authenticates with the authorization server, which issues an authorization code. This code is then exchanged for an access token. + +This method protects user credentials and prevents them from being compromised by malicious client applications. + +### Refresh token grant + +A refresh token allows you to obtain a new access token when the current one expires or when a new token is needed. The refresh token grant type is used for this purpose. Refresh tokens are optional and, if issued, are included in the response along with the access token. You can use the refresh token to request a new access token from the authorization server. Choreo's default authorization server, Asgardeo, issues refresh tokens for all grant types except the **Client Credentials** grant type, as recommended by the OAuth 2.0 specification. + +!!! note + - Treat refresh tokens as securely as access tokens. + - No user interaction is required to obtain a new access token using the Refresh Token grant type. + +### Client credentials grant + +The Client Credentials flow allows client applications to obtain an access token without user authentication. This is useful when the client application needs to access its own resources, such as data storage or APIs, but does not require access to user data. Ensure that client credentials are kept secure, as anyone with these credentials can obtain access tokens and access the client's resources. + +### Implicit grant + +The Implicit Grant flow allows a client application to obtain an access token directly from the authorization server without an intermediate authorization code exchange. This flow is commonly used in browser-based applications. + +However, the access token is exposed in the browser's URL fragment, making it vulnerable to attacks like cross-site scripting (XSS). As a result, this flow is not recommended for applications requiring high security. + +### Password grant + +The Password Grant flow allows a client application to obtain an access token by directly providing the user's username and password to the authorization server. This method is less secure than other grant types because the client application handles and transmits the user's credentials. + +This grant type is typically used in highly trusted client applications where user experience is prioritized over security. It is not recommended for public-facing applications or scenarios involving sensitive data. + +## Revoke access tokens + +Revoking JWT access tokens can be challenging because they are self-validating. Once issued, a token contains all the information needed to validate its authenticity without requiring server-side lookups. + +It is recommended to set an expiry time of no more than 900 seconds. + +In traditional session-based authentication, the server can revoke a session by invalidating its session ID. However, JWTs do not rely on a central authority to track valid or invalid tokens. Revoking a JWT requires techniques like denylists or allowlists, which can complicate the authentication process and may not always be foolproof. + +To address these challenges, use short-lived JWT access tokens and refresh them regularly. This reduces the risk of unauthorized access if a token is stolen or leaked. Additionally, implementing strong encryption and secure token storage can further enhance JWT-based authentication security. + +By default, the Choreo Developer Portal sets the token lifespan to 15 minutes (900 seconds). Application developers can increase this time if necessary, but it is recommended to keep it as short as possible. \ No newline at end of file diff --git a/en/docs/consuming-services/manage-subscription.md b/en/developer-docs/docs/consuming-services/manage-subscription.md similarity index 100% rename from en/docs/consuming-services/manage-subscription.md rename to en/developer-docs/docs/consuming-services/manage-subscription.md diff --git a/en/developer-docs/docs/consuming-services/share-applications.md b/en/developer-docs/docs/consuming-services/share-applications.md new file mode 100644 index 000000000..c8a7e2c64 --- /dev/null +++ b/en/developer-docs/docs/consuming-services/share-applications.md @@ -0,0 +1,20 @@ +# Share Applications + +Choreo's application-sharing feature allows you to share your applications with members within your organization. This promotes collaboration when multiple members need to work on the same application. + +Follow these steps to share an application with members of your organization: + +1. Go to the [Choreo Developer Portal](https://devportal.choreo.dev/) and click the **Applications** tab. + +2. On the **Applications** page, click on the application you want to share. + +3. On the **Application Overview** page, click the **Share** button on the right side. + +4. In the **Share Application** dialog, enter the email addresses of the members you want to share the application with. + + !!! note + You must type an email address and press **Enter** to add it. + +5. Click **Confirm**. The application will be shared in read-only mode with the specified members. + +To view the members with whom the application is shared, go to the **Application Overview** page and check the email addresses listed in the **Shared with** field. diff --git a/en/docs/develop-components/bring-your-own-image.md b/en/developer-docs/docs/develop-components/bring-your-own-image.md similarity index 97% rename from en/docs/develop-components/bring-your-own-image.md rename to en/developer-docs/docs/develop-components/bring-your-own-image.md index 192bbfa01..9ef608cda 100644 --- a/en/docs/develop-components/bring-your-own-image.md +++ b/en/developer-docs/docs/develop-components/bring-your-own-image.md @@ -149,19 +149,20 @@ Follow the guidelines below based on your container registry: 1. In the left navigation, click **Overview** and select your project. Alternatively, select your project from the **Project** list in the Choreo Console header. 2. Under **Component Listing** click **+ Create**. 3. Select your component type (BYOI is only available for Service, Web Application, Scheduled Task, or Manual Task components). -4. Enter a display name, a unique name, and a description for the component. - - !!! info - In the **Component Name** field, you must specify a name to uniquely identify the component in various contexts. The value is editable only at the time you create the component. You cannot change the name after you create the component. - -5. Click either the **Docker Hub** tab or the **Container Registry** tab depending on your vendor. -6. Under **Deploy an image from Container Registry/Docker Hub**, select the container registry you have registered in [Step 1](#step-1-register-a-container-registry). -7. Enter the full image URL. The image URL format in general is as follows: +4. From the Create Component pane, select the **Container Registry** under the **Connect a Docker Image** section. +5. Under **Deploy an image from Container Registry/Docker Hub**, select the container registry you have registered in [Step 1](#step-1-register-a-container-registry). +6. Enter the full image URL. The image URL format in general is as follows: `[container-registry-host]/[repository-name]/[image-name]:[tag]` !!! tip When a public image from Docker Hub lacks a specified repository name, it typically defaults to `/library/`. For example, you can access the public Nginx image `https://hub.docker.com/_/nginx` as `registry.hub.docker.com/library/nginx:1.25`. +7. Enter a display name, a unique name, and a description for the component. + + !!! info + In the **Component Name** field, you must specify a name to uniquely identify the component in various contexts. The value is editable only at the time you create the component. You cannot change the name after you create the component. + + ## Step 3: Deploy the component in Choreo To deploy the component and bring your image to Choreo, follow the steps given below: diff --git a/en/docs/develop-components/configure-endpoints-body.md b/en/developer-docs/docs/develop-components/configure-endpoints-body.md similarity index 100% rename from en/docs/develop-components/configure-endpoints-body.md rename to en/developer-docs/docs/develop-components/configure-endpoints-body.md diff --git a/en/docs/develop-components/configure-endpoints.md b/en/developer-docs/docs/develop-components/configure-endpoints.md similarity index 100% rename from en/docs/develop-components/configure-endpoints.md rename to en/developer-docs/docs/develop-components/configure-endpoints.md diff --git a/en/docs/develop-components/deploy-a-containerized-application.md b/en/developer-docs/docs/develop-components/deploy-a-containerized-application.md similarity index 95% rename from en/docs/develop-components/deploy-a-containerized-application.md rename to en/developer-docs/docs/develop-components/deploy-a-containerized-application.md index c81226553..cf6a55881 100644 --- a/en/docs/develop-components/deploy-a-containerized-application.md +++ b/en/developer-docs/docs/develop-components/deploy-a-containerized-application.md @@ -36,13 +36,13 @@ To connect your GitHub repository to Choreo, you should authorize the [Choreo Ap !!! note You can [revoke access](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/reviewing-your-authorized-integrations#reviewing-your-authorized-github-apps) if you do not want Choreo to have access to your GitHub account. Choreo needs write access only to send pull requests to a user repository. Choreo does not directly push any changes to a repository. -Alternatively, you can connect a public repository without requiring authorization from the [Choreo Apps](https://github.com/marketplace/choreo-apps) GitHub application. You can paste a public repository URL in the **Provide Repository URL** field at the time of component creation. +Alternatively, you can connect a public repository without requiring authorization from the [Choreo Apps](https://github.com/marketplace/choreo-apps) GitHub application. Select the **Third-Party GitHub Repository** and paste a public repository URL in the **Public Repository URL** field at the time of component creation. !!! tip Authorizing the repository with the [Choreo Apps](https://github.com/marketplace/choreo-apps) GitHub application becomes essential if you want to enable [**Auto Deploy**](https://wso2.com/choreo/docs/choreo-concepts/ci-cd/#deploy) for the component. If you own the repository, you can subsequently authorize it with the [Choreo Apps](https://github.com/marketplace/choreo-apps) GitHub application to enable **Auto Deploy**. After granting access to the required repositories, you can choose a repository and an associated branch to connect to the Choreo component. -For the containerized application deployments, you should select the **Dockerfile** as the **Buildpack** and provide **Dockerfile Path** and [**Docker Context Path**](https://docs.docker.com/build/building/context/#path-context) for the Docker build. +For the containerized application deployments, you should select the [**Component Directory**](https://docs.docker.com/build/building/context/#path-context), **Dockerfile** as the **Buildpack** and provide **Dockerfile Path** for the Docker build. ![Connected Dockerfile Repository](../assets/img/develop-components/deploy/create-component-connected-repo.png){.cInlineImage-full} @@ -55,7 +55,7 @@ The following table describes the individual fields in the **Create Component** | **Branch** | The branch of the repository. | | **Buildpack** | Determines the implementation of the component: Any language or other language as a Docker container. | | **Dockerfile Path** | The path to your Dockerfile. This path is defined relative to the repository root.
For example, if the Dockerfile is at the repository root, the value for this field is `/Dockerfile`. | -| **Docker Context Path** | The Docker build context path. To include the repository root, leave the default `/` value. | +| **Component Directory** | The component directory path. To include the repository root, leave the default `/` value. | | **Port*** | The port at which your service is running. | | **OpenAPI Filepath*** | The path to an OpenAPI specification (in YAML/JSON) relative to the repository root. If you don't provide a path, the system automatically generates a default allow-all specification. | diff --git a/en/docs/develop-components/deploy-an-application-with-buildpacks.md b/en/developer-docs/docs/develop-components/deploy-an-application-with-buildpacks.md similarity index 100% rename from en/docs/develop-components/deploy-an-application-with-buildpacks.md rename to en/developer-docs/docs/develop-components/deploy-an-application-with-buildpacks.md diff --git a/en/developer-docs/docs/develop-components/develop-a-webhook.md b/en/developer-docs/docs/develop-components/develop-a-webhook.md new file mode 100644 index 000000000..8a52e6c8f --- /dev/null +++ b/en/developer-docs/docs/develop-components/develop-a-webhook.md @@ -0,0 +1,133 @@ +# Develop a Webhook + +Choreo allows developers to design high-quality webhooks. To explore this capability, let's consider a scenario where a team of software engineers in an organization should be notified via email whenever someone creates a GitHub issue with the `bug` label in a specific repository. + +In this tutorial, you will address the requirement by doing the following: + +- Create a webhook by connecting to a forked GitHub repository where you have the webhook implementation that addresses the described requirement. +- Deploy the webhook to the development environment. +- Modify the webhook implementation to connect the webhook to GitHub, enabling it to act in response to selected GitHub-related events. +- Test the webhook. +- Promote the webhook to the production environment. + +## Prerequisites + +1. If you're signing in to the Choreo Console for the first time, create an organization: + 1. Go to [https://console.choreo.dev/](https://console.choreo.dev/) and sign in using your preferred method. + 2. Enter a unique organization name. For example, `Stark Industries`. + 3. Read and accept the privacy policy and terms of use. + 4. Click **Create**. + + This creates the organization and opens the **Project Home** page of the default project created for you. + +2. Fork the [Choreo samples repository](https://github.com/wso2/choreo-samples), which contains the sample integration for this guide. + +## Step 1: Create a webhook component + +To create a Webhook component, follow these steps: + +1. Go to [https://console.choreo.dev/](https://console.choreo.dev/) and sign in using your preferred method. +2. If you already have one or more components in your project, click **+ Create**. Otherwise, proceed to the next step. +3. Click the **Webhook** card. +4. Click **Authorize with GitHub** to connect Choreo to your GitHub account. If you haven't connected your GitHub repository to Choreo, enter your credentials and select the repository you forked earlier to install the [Choreo GitHub App](https://github.com/marketplace/choreo-apps). + + Alternatively, select the **Use Public GitHub Repository** option and paste the [Choreo samples repository](https://github.com/wso2/choreo-samples) URL in the **Provide Repository URL** field. However, enabling [**Auto Deploy**](https://wso2.com/choreo/docs/choreo-concepts/ci-cd/#deploy) requires authorizing the repository with the [Choreo GitHub App](https://github.com/marketplace/choreo-apps). + + !!! note + The **Choreo GitHub App** requires: + - Read and write access to code and pull requests. + - Read access to issues and metadata. + + You can [revoke access](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/reviewing-your-authorized-integrations#reviewing-your-authorized-github-apps) at any time. Write access is only used for sending pull requests; Choreo will not push changes directly to your repository. + +5. Enter the following information: + + | **Field** | **Description** | + |-------------------------------|--------------------| + | **GitHub Account** | Your account | + | **GitHub Repository** | choreo-samples | + | **Branch** | main | + | **Component Path** | `github-event-to-email-webhook` | + +6. Select **Ballerina** as the build pack. +7. Provide a display name, a unique name and description for the component. +8. Click **Create**. + +Choreo creates the Webhook component with the sample implementation and opens the component **Overview** page. + +## Step 2: Deploy + +To deploy the webhook to the development environment, follow these steps: + +1. In the Choreo Console left navigation menu, click **Deploy**. +2. In the **Build Area** card, click **Configure & Deploy**. +3. In the **Configurations** pane, enter the following information: + 1. In the **webhookSecret** field, enter any value. + + !!! note + Save this value for later use. + + 2. In the **toEmail** field, enter the email address to send notification emails. + 3. Click **Deploy**. + + You can monitor the deployment progress in the **Console** pane that opens on the right of the page. + +Once Choreo completes the deployment, the **Development** card indicates the **Deployment Status** as **Active**. + +!!! note + In the deployment card, you can click the icon corresponding to configurables to open the **Configurations** pane and edit configurations. + +## Step 3: Connect the webhook to the GitHub repository + +To allow the webhook to read the labels of issues in a specific GitHub repository, connect the webhook to the GitHub repository: + +1. In the Choreo Console left navigation menu, click **Overview**. +2. On the **Overview** page, copy the invoke URL by clicking the copy icon within the **URL** field. +3. Go to your GitHub account and open the repository for which you want to generate notification emails. +4. In the top menu, click the **Settings** tab. +5. In the left navigation menu, click **Webhooks**. +6. Click **Add webhook** and enter the following information: + + | **Field** | **Value** | + |------------------|--------------------------------------------------------------------| + | **Payload URL** | The invoke URL you copied in Step 3, sub-step 1. | + | **Content Type** | Select `application/json` | + | **Secret** | The last webhook secret you configured in [Step 2](#step-2-deploy).| + + !!! tip + - **Buildpack** specifies the type of build to run depending on the implementation of the component. It converts the integration code into a Docker image that can run on Choreo cloud. If an integration is developed using [WSO2 Integration Studio](https://wso2.com/integration/integration-studio/), select **Micro Integrator** as the buildpack. If an integration is developed using the [Ballerina language](https://ballerina.io), select **Ballerina** as the buildpack. + - **Project Path** specifies the location of the project to build the component. + +7. Under **Which events would you like to trigger this webhook?**, select **Let me select individual events**. +8. Select the **Issues** checkbox in the list of events displayed. This ensures that GitHub issues trigger the webhook. +9. Clear the **Pushes** checkbox to ensure that GitHub does not trigger your webhook when the team pushes changes to the selected GitHub repository. +10. Click **Add webhook** to save the configuration. + +Now you have integrated Choreo with GitHub via the webhook you created and deployed. You can proceed to test the webhook. + +## Step 4: Test + +To test your webhook, create a GitHub issue with the `Bug` label in the repository that you connected to the webhook. You will receive an email similar to the following at the email address you provided in [Step 2](#step-2-deploy). + +## Step 5: Promote + +To promote the webhook to the Production environment, follow these steps: + +1. On the **Deploy** page, go to the **Development** card and click **Promote**. +2. In the **Configuration Types** pane, leave the default selection (i.e., **Use default configuration values**) unchanged. + + !!! note + If you have configured any default values for the configurable variables, selecting **Use default configuration values** allows you to proceed with those values. If not, specify values for the configurable variables. + +3. Click **Next**. +4. In the **webhookSecret** field, enter any value. + + !!! note + Save this value for later use. + +5. In the **toEmail** field, enter the email address to send notification emails. +6. Click **Promote**. + + Once the component is promoted to production, the **Production** card displays the deployment status as **Active**. + +Now you have successfully created, deployed, and tested a Webhook component and promoted it to production. diff --git a/en/developer-docs/docs/develop-components/develop-an-api-proxy.md b/en/developer-docs/docs/develop-components/develop-an-api-proxy.md new file mode 100644 index 000000000..ca89f6cd3 --- /dev/null +++ b/en/developer-docs/docs/develop-components/develop-an-api-proxy.md @@ -0,0 +1,140 @@ +# Develop an API Proxy + +An API proxy acts as an intermediary between an existing API and Choreo, intercepting all requests made to the API. It also functions as a managed API, allowing you to apply essential API management features such as security policies and rate limiting. + +In this guide, you will: + +- Create an API proxy component to expose an existing API. +- Deploy the API proxy. +- Test the API proxy to verify its functionality. +- Manage the API. +- Consume the API. + +## Prerequisites + +- If you're signing in to the Choreo Console for the first time, create an organization: + 1. Go to [https://console.choreo.dev/](https://console.choreo.dev/) and sign in using your preferred method. + 2. Enter a unique organization name. For example, `Stark Industries`. + 3. Read and accept the privacy policy and terms of use. + 4. Click **Create**. + + This creates the organization and opens the **Project Home** page of the default project created for you. + +## Step 1: Create an API proxy + +To create an API proxy, you can either upload an OpenAPI specification or provide an OpenAPI specification URL. In this guide, you will specify a URL to an OpenAPI definition of a sample API. + +1. Go to [https://console.choreo.dev/](https://console.choreo.dev/) and sign in. This opens the project home page. +2. If you already have one or more components in your project, click **+ Create**. Otherwise, proceed to the next step. +3. Click the **API Proxy** card. This opens the **Create an API Proxy** pane. +4. Click **Skip Source** to define resources manually. +5. Specify the following values as API proxy details: + + !!! info + The **Name** field must be unique and cannot be changed after creation. + + | **Field** | **Value** | + |-----------------|--------------------------------------------| + | **Display Name**| `HR API` | + | **Name** | `hr-api` | + | **Context** | `abc-hr` | + | **Version** | `1.0` | + | **Target** | `https://samples.choreoapps.dev/company/hr`| + | **Access Mode** | **External** | + +6. Click **Create**. This creates the API proxy component and takes you to the **Overview** page. + +## Step 2: Define resources for the API proxy + +To add a new resource that retrieves a department by the department ID, follow these steps: + +1. In the left navigation menu, click **Develop** and then click **Resources**. +2. Select **GET** as the **HTTP Verb** and enter `/department/{departmentId}` as the **URI Pattern**. +3. Click **+** to add the resource. +4. Expand the added resource and specify the following values: + + | **Field** | **Value** | + |------------------|--------------------------------------| + | **Operation ID** | `findDepartment` | + | **Description** | `Find a department by department ID` | + +5. Remove the five default resources that start with `/*` by clicking the delete icon corresponding to each resource. +6. Click **Save**. + +## Step 3: Deploy the API proxy + +1. In the left navigation menu, click **Deploy**. +2. In the **Build Area** card, click **Configure & Deploy**. This opens the **Configure & Deploy** pane. +3. Select **External** as the API access mode and click **Deploy**. The **Development** card indicates the **Deployment Status** as **Active** when the API proxy is successfully deployed. + +Now you are ready to test the API proxy. + +## Step 4: Test the API proxy + +Choreo allows you to test your API proxy using either the [integrated OpenAPI Console](../testing/test-rest-endpoints-via-the-openapi-console.md) or [cURL](../testing/test-apis-with-curl.md). In this guide, you will use the OpenAPI Console. + +!!! tip + Choreo enables OAuth 2.0 to secure APIs by default. Therefore, you need an access token to invoke an API. + + - Choreo automatically generates a key to test the API via the OpenAPI Console. To view the key, click the show key icon in the **Security Header** field. + - To disable security for the entire API or a specific resource: + 1. In the left navigation menu, click **Deploy**. + 2. Go to the **Build Area** card and click **Security Settings**. + 3. In the **Security Settings** pane: + - To disable security for the entire API, clear the **OAuth2** checkbox. + - To disable security for a specific resource, expand the relevant resource and turn off the **Security** toggle. + 4. Click **Apply**. + +1. In the left navigation menu, click **Test** and then click **OpenAPI Console**. +2. Select **Development** from the environment drop-down list. +3. Expand the `GET /department/{departmentId}` resource and click **Try it Out**. +4. Enter `1` as the **departmentId** and click **Execute**. You will see a response similar to the following: + + ![API proxy response](../assets/img/develop-components/develop-a-rest-api-proxy/rest-api-proxy-response.png){.cInlineImage-full} + + This indicates that your API proxy is working as expected. + +## Step 5: Manage the API proxy + +Now that you have a tested API proxy, you can publish it and make it available for application developers to consume. In this guide, you will apply rate limiting to the API and publish it. + +### Step 5.1: Apply rate limiting to the API proxy + +1. In the left navigation menu, click **Deploy**. +2. Go to the required environment card and click the settings icon corresponding to **API Configuration**. +3. In the **API Configuration** pane, click **Rate Limiting** to expand the section. +4. Select **API Level** as the **Rate Limiting Level**. +5. Specify appropriate values for the **Request Limit** and **Time Unit** fields. You can proceed with the default values. +6. Click **Apply**. This applies the rate limiting level to the API proxy and redeploys it. + +### Step 5.2: Publish the API proxy + +1. In the left navigation menu, click **Lifecycle** under **Manage**. This takes you to the **Lifecycle** page. +2. Click **Publish**. +3. In the **Publish API** dialog, click **Confirm** to proceed with publishing the API. If you want to change the display name, make the necessary changes and then click **Confirm**. This changes the API lifecycle state to **Published**. + +## Step 6: Invoke the API + +To generate credentials for the published API and invoke it via the Choreo Developer Portal, follow these steps: + +1. In the **Lifecycle** page, click **Go to Devportal**. This takes you to the `HR API` in the Choreo Developer Portal. + +2. **Generate Credentials**: + 1. In the Developer Portal left navigation menu, click **Production** under **Credentials**. + 2. Click **Generate Credentials**. Choreo generates new tokens and populates the **Consumer Key** and **Consumer Secret** fields. + + !!! tip + To test the API via an API test tool or through code, click **Generate Access Token** and copy the test token. Alternatively, click **cURL** and copy the generated cURL command to use via a cURL client. You do not need to generate an access token if you are testing the API via the **Try Out** capability in the Choreo Developer Portal. + +3. **Invoke the API**: + 1. In the Developer Portal left navigation menu, click **Try Out**. + 2. In the **Endpoint** list, select **Development** as the environment to try out the API. + 3. Click **Get Test Key** to generate an access token. + 4. Expand the `GET /department/{departmentId}` resource and click **Try it out**. + 5. Enter `1` as the **departmentId** and click **Execute**. You will see a response similar to the following: + + ![Try out response](../assets/img/develop-components/develop-a-rest-api-proxy/try-out-response.png){.cInlineImage-full} + +Now, you have gained hands-on experience creating, deploying, testing, and publishing an API proxy using Choreo API Manager. + +To learn more about the API management capabilities supported by Choreo API Manager, see [API Management](../api-management/lifecycle-management.md). diff --git a/en/docs/develop-components/develop-an-external-consumer.md b/en/developer-docs/docs/develop-components/develop-an-external-consumer.md similarity index 100% rename from en/docs/develop-components/develop-an-external-consumer.md rename to en/developer-docs/docs/develop-components/develop-an-external-consumer.md diff --git a/en/docs/develop-components/develop-components-using-vs-code.md b/en/developer-docs/docs/develop-components/develop-components-using-vs-code.md similarity index 100% rename from en/docs/develop-components/develop-components-using-vs-code.md rename to en/developer-docs/docs/develop-components/develop-components-using-vs-code.md diff --git a/en/docs/develop-components/develop-components-with-git.md b/en/developer-docs/docs/develop-components/develop-components-with-git.md similarity index 83% rename from en/docs/develop-components/develop-components-with-git.md rename to en/developer-docs/docs/develop-components/develop-components-with-git.md index 572d36d68..48dd4f5b9 100644 --- a/en/docs/develop-components/develop-components-with-git.md +++ b/en/developer-docs/docs/develop-components/develop-components-with-git.md @@ -43,7 +43,7 @@ Choreo provides [Git submodule](https://git-scm.com/book/en/v2/Git-Tools-Submodu For example, when you [work with the Micro Integrator (MI) runtime in Choreo](./work-with-the-micro-integrator-runtime-in-choreo.md), you can use Git submodules to reuse MI templates and sequences across components without duplication. -!!! tip +!!! info "Note" If you encounter an error stating that you cannot clone a submodule due to insufficient permissions, follow the instructions below to grant the necessary permissions: - For a personal account: @@ -62,9 +62,30 @@ For example, when you [work with the Micro Integrator (MI) runtime in Choreo](./ 4. Click **Configure** corresponding to **choreo.dev**. 5. Under **Repository Access**, grant access to the necessary repositories. - !!! info "Note" + !!! note Choreo currently does not support accessing private repositories in other organizations. +#### Automatically pull latest versions of Git submodules + +Choreo lets you automatically pull the latest versions of Git submodules from their respective repositories. To enable this feature, follow these steps: + +!!! note + Choreo currently supports this feature only for components where the buildpack is **WSO2 MI**. + +1. Sign in to the [Choreo Console](https://console.choreo.dev/). +2. In the **Component Listing** pane, click the component for which you want to pull the latest versions of Git submodules. +3. In the left navigation menu, click **Build**. +4. On the **Build** page, click to edit **Build Configurations**. +5. Turn on the **Pull Latest Submodules** toggle. + + !!! info "Note" + If you rebuild a previously built commit and it doesn’t reflect the latest changes, follow these steps to ensure the changes are applied to the deployed environment: + + 1. In the Choreo Console left navigation menu, click **DevOps**, then click **Containers**. + 2. Click **Edit** to update the container settings. + 3. Select **Always** as the **Image Pull Policy**. + 4. Click **Save Changes**. + ## Authorize Bitbucket with Choreo Authorizing using a personal access token (PAT) from Bitbucket grants Choreo the following permissions to perform the respective actions on your behalf within the repository. diff --git a/en/developer-docs/docs/develop-components/develop-integrations/develop-a-manual-task.md b/en/developer-docs/docs/develop-components/develop-integrations/develop-a-manual-task.md new file mode 100644 index 000000000..7f7c01553 --- /dev/null +++ b/en/developer-docs/docs/develop-components/develop-integrations/develop-a-manual-task.md @@ -0,0 +1,204 @@ +# Develop a Manual Task + +This guide walks you through the steps to develop, deploy, test, and observe a manual task using Choreo. + +In this guide, you will: + +- Develop a manual task to fetch the weather forecast for a specified location for the next 24 hours from the [OpenWeatherMap](https://openweathermap.org) API. +- Process the weather data into a specific format. +- Send the formatted data to a specified email address. + +## Prerequisites + +1. If you're signing in to the Choreo Console for the first time, create an organization: + 1. Go to [https://console.choreo.dev/](https://console.choreo.dev/) and sign in. + 2. Enter a unique organization name. For example, `Stark Industries`. + 3. Read and accept the privacy policy and terms of use. + 4. Click **Create**. + + This creates the organization and opens the **Project Home** page of the default project created for you. + +2. Fork the [Choreo samples repository](https://github.com/wso2/choreo-samples), which contains the sample integration for this guide. + + !!! info "Repository File Structure" + The sample code for this guide is in the `/weather-to-email-integration` directory. The following table describes the key files in the repository: + + | **File Path** | **File Content** | + | --------------------- | -------------------------------------------------------------------- | + | **Ballerina.toml** | Contains metadata about the project | + | **Dependencies.toml** | Lists the dependencies required for the project | + | **main.bal** | Contains the entry point of the project, including the main function | + | **types.bal** | Contains custom data types used in the project | + | **utils.bal** | Contains utility functions and helper functions used in the project | + +3. Go to [OpenWeatherMap](https://openweathermap.org/) and sign up to obtain an API key. For details, see the [OpenWeatherMap documentation](https://openweathermap.org/appid#signup). + +## Step 1: Create a manual task component + +1. Go to [https://console.choreo.dev/](https://console.choreo.dev/) and sign in. This opens the project home page. +2. If you already have one or more components in your project, click **+ Create**. Otherwise, proceed to the next step. +3. Click the **Manual Task** card. +6. Click **Authorize with GitHub** to connect Choreo to your GitHub account. If you haven't connected your GitHub repository to Choreo, enter your credentials and select the repository you forked earlier to install the [Choreo GitHub App](https://github.com/marketplace/choreo-apps). + + Alternatively, select the **Use Public GitHub Repository** option and paste the [Choreo samples repository](https://github.com/wso2/choreo-samples) URL in the **Provide Repository URL** field. However, enabling [**Auto Deploy**](https://wso2.com/choreo/docs/choreo-concepts/ci-cd/#deploy) requires authorizing the repository with the [Choreo GitHub App](https://github.com/marketplace/choreo-apps). + + !!! note + The **Choreo GitHub App** requires: + + - Read and write access to code and pull requests. + - Read access to issues and metadata. + + You can [revoke access](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/reviewing-your-authorized-integrations#reviewing-your-authorized-github-apps) at any time. Write access is only used for sending pull requests; Choreo will not push changes directly to your repository. + +7. Enter the following information: + + | **Field** | **Description** | + | ----------------------| -----------------------------------------------------| + | **Organization** | Your GitHub account | + | **Repository** | `choreo-samples` | + | **Branch** | `main` | + | **Component Directory** | `weather-to-email-integration` | + +8. Select **Ballerina** as the **Build Pack**. + + !!! tip + - **Buildpack** specifies the type of build to run depending on the implementation of the component. It converts the integration code into a Docker image that can run on Choreo cloud. If an integration is developed using [WSO2 Integration Studio](https://wso2.com/integration/integration-studio/), select **Micro Integrator** as the buildpack. If an integration is developed using the [Ballerina language](https://ballerina.io), select **Ballerina** as the buildpack. + - **Component Directory** specifies the location of the project to build the component. + +4. Enter a unique name and description for the component. You can use the following values: + + | **Field** | **Value** | + | ------------------ | -------------------------------- | + | **Component Name** | `WeatherToEmail` | + | **Description** | `My first manual task` | + + +8. Click **Create**. Choreo initializes the component with the sample implementation and opens the **Overview** page of the component. + +## Step 2: Build the manual task + +1. In the left navigation menu, click **Build**. +2. In the **Builds** pane, click **Build**. This opens the **Commits** pane, where you can see all the commits related to the component. +3. Select the latest commit and click **Build**. This triggers the build process and displays the build progress in the **Build Logs** pane. + + !!! info + The build process may take some time. Once complete, the build status will be listed in the **Builds** pane. Here, you will see the build status as **Success**. + +## Step 3: Deploy the manual task + +1. In the left navigation menu, click **Deploy**. +2. In the **Set Up** card, click **Configure & Deploy**. +3. In the **Configurations** pane, specify values for the configurable variables: + + !!! tip + The configurable variables populated here are defined in the sample Ballerina project used in this guide. To learn how to declare configurable variables in Ballerina, see the [Ballerina documentation on declaring configurable variables](https://ballerina.io/learn/by-example/configurable-variables/). + + | **Field** | **Value** | + | ------------- | ----------------------------------------------------------------------- | + | **apiKey** | The API key you obtained in the prerequisites section | + | **latitude** | Latitude of the location to get the weather forecast | + | **longitude** | Longitude of the location to get the weather forecast | + | **email** | The email address to receive the formatted weather forecast information | + + !!! note + If you use **Ballerina** as the buildpack and want to set a configurable variable as a secret, click the lock icon corresponding to the configurable variable. This marks it as a secret and conceals the input value. + + For example, if you set the **apiKey** as a secret, its input value will be concealed. To update the input value later, click **Update Secret Content** and specify a new value. + +4. Click **Deploy**. + +## Step 4: Execute the manual task + +1. In the left navigation menu, click **Execute**. +2. Click **Run Now**. This triggers the task. + + !!! info "Inject Dynamic Values into Your Application as Command-Line Arguments" + If you want to inject dynamic values into your application as command-line arguments when you run a manual task, follow these steps: + 1. Click the drop-down icon next to **Run Now** and then click **Run with Arguments**. + 2. In the **Runtime Arguments** pane, enter the arguments you want to pass to your application. + 3. Click **Execute**. This triggers the task with the specified arguments. + + The capability to run a manual task with arguments is supported for the following buildpacks: + + === "Dockerfile" + To explore a Dockerfile-based manual task with arguments, try out the [Hello World Task](https://github.com/wso2/choreo-samples/tree/main/docker-hello-world-manual-task) sample. For instructions, see the `readme.md` file in the sample repository. + + !!! info + When working on Docker projects, the **Run with Arguments** capability is not supported if the Dockerfile contains `CMD`. In such scenarios, use `ENTRYPOINT` to define your default commands. + + === "Go" + To explore a Go-based manual task with arguments, try out the [Hello World Go Task](https://github.com/wso2/choreo-samples/tree/main/hello-world-go-task) sample. For instructions, see the `readme.md` file in the sample repository. + + === "Java" + To explore a Java-based manual task with arguments, try out the [Hello World Java Task](https://github.com/wso2/choreo-samples/tree/main/hello-world-java-task) sample. For instructions, see the `readme.md` file in the sample repository. + + !!! info + When working on Java projects: + - The **Run with Arguments** capability is not supported if `Procfile` is available in the project. + - The `Main` class should be defined in the `manifest` file. + - If Maven files such as `mvn.cmd` exist in the project without the `.mvn` directory, the build will fail. To ensure a successful build, either commit the `.mvn` directory along with any Maven files or exclude Maven files if you choose not to commit the `.mvn` directory. + + === "NodeJS" + To explore a NodeJS-based manual task with arguments, try out the [Hello World NodeJS Task](https://github.com/wso2/choreo-samples/tree/main/hello-world-nodejs-task) sample. For instructions, see the `readme.md` file in the sample repository. + + !!! info + When working on NodeJS projects: + - The **Run with Arguments** capability is not supported if `Procfile` is available in the project. + - The project root must contain the `package.json` file with the `main` attribute defined. + + === "WSO2 MI" + To explore a WSO2 MI-based manual task with arguments, try out the [Weather to Logs Task](https://github.com/wso2/choreo-samples/tree/main/weather-to-logs-mi-manual-task) sample. For instructions, see the `readme.md` file in the sample repository. + + !!! info + When working on WSO2 MI projects and deploying a WSO2 MI integration as a manual task in Choreo, use the WSO2 MI automation mode. For details, see [Running the Micro Integrator in Automation Mode](https://apim.docs.wso2.com/en/latest/install-and-setup/install/running-the-mi-in-automation-mode/). + + === "Ballerina" + To explore a Ballerina manual task with arguments, try out the [Weather to Email Task](https://github.com/wso2/choreo-samples/tree/main/weather-to-email-integration) sample. For instructions, see the README.md file in the sample repository. + + !!! info + If you want to pass arguments to Ballerina main functions, use the **Run with Arguments** capability. For details on the arguments you can pass, see the [Ballerina documentation](https://ballerina.io/learn/by-example/main-function/). You can also override configurable values in the same manner. For more information, see [Provide values to configurable variables](https://ballerina.io/learn/provide-values-to-configurable-variables/#provide-via-command-line-arguments). + +## Step 5: Test the manual task + +Once the task is triggered, an email with the subject `[WSO2 Choreo Demo] Next 24H Weather Forecast` is sent from `choreo.demo@gmail.com` to the email address specified as the **email** configurable variable value in [Step 3](#step-3-deploy-the-manual-task). + +If the manual task ran successfully, you should receive an email similar to the following: + +![Received email](../../assets/img/develop-components/develop-a-scheduled-integration/Received-email.png) + +## Step 6: Observe the manual task + +The observability view in Choreo displays graphs that depict details such as throughput, latency, diagnostic data, and logs to identify and troubleshoot anomalies in components you deploy. + +1. In the left navigation menu, click **Observability**. +2. Observe the following: + - The throughput and latencies of requests served over a given period. + - The logs generated over a given period. + - The flame graph (Diagnostics View) generated over a given period. + - The low-code diagram. + +To learn more about the observability details you can view via Choreo observability, see [Observability Overview](../../monitoring-and-insights/observability-overview.md). + +## Step 7: Monitor executions + +To track and monitor executions associated with the deployed manual task, go to the left navigation menu and click **Execute**. + +!!! tip + The **Execute** view is applicable to both scheduled and manual tasks. + +You can view the following information: + +- **Total executions**: The total number of executions within the past 30 days. + + ![Total Execution](../../assets/img/develop-components/develop-a-scheduled-integration/total_executions.png) + +- **Execution history**: The currently active executions and those that are already complete. You can view information such as the execution ID, the revision of the execution, and the time it was triggered. + + ![Execution History](../../assets/img/develop-components/develop-a-scheduled-integration/execution_history.png) + +- **Detailed execution logs**: Click on an execution to view detailed logs related to it. + + !!! info + It may take a few minutes for the logs to appear. You may need to manually refresh to view the latest logs. + + ![Execution Logs](../../assets/img/develop-components/develop-a-scheduled-integration/execution_logs.png) diff --git a/en/developer-docs/docs/develop-components/develop-integrations/develop-a-scheduled-task.md b/en/developer-docs/docs/develop-components/develop-integrations/develop-a-scheduled-task.md new file mode 100644 index 000000000..5978bcd9e --- /dev/null +++ b/en/developer-docs/docs/develop-components/develop-integrations/develop-a-scheduled-task.md @@ -0,0 +1,170 @@ +# Develop a Scheduled Task + +Choreo is a versatile integration platform that allows you to create various types of integrations depending on your requirements. If you need to automatically run a specific integration at regular intervals, you can use Choreo to develop a scheduled task. This type of integration can automate the synchronization of data between different systems at specified intervals, reducing errors and improving productivity by eliminating the need for manual intervention. + +This guide walks you through the steps to develop, deploy, test, and observe a scheduled task using Choreo. + +In this guide, you will: + +- Develop a scheduled task to fetch the weather forecast for a specified location for the next 24 hours from the [OpenWeatherMap](https://openweathermap.org) API. +- Process the weather data into a specific format. +- Send the formatted data to a specified email address at a specific time every day. + +## Prerequisites + +1. If you're signing in to the Choreo Console for the first time, create an organization: + 1. Go to [https://console.choreo.dev/](https://console.choreo.dev/) and sign in using your preferred method. + 2. Enter a unique organization name. For example, `Stark Industries`. + 3. Read and accept the privacy policy and terms of use. + 4. Click **Create**. + + This creates the organization and opens the **Project Home** page of the default project created for you. + +2. Fork the [Choreo samples repository](https://github.com/wso2/choreo-samples), which contains the sample integration for this guide. + + !!! info "Repository File Structure" + The sample code for this guide is in the `/weather-to-email-scheduled-task` directory. The following table describes the key files in the repository: + + | **File Path** | **File Content** | + | --------------------- | -------------------------------------------------------------------- | + | **Ballerina.toml** | Contains metadata about the project | + | **Dependencies.toml** | Lists the dependencies required for the project | + | **main.bal** | Contains the entry point of the project, including the main function | + | **types.bal** | Contains custom data types used in the project | + | **utils.bal** | Contains utility functions and helper functions used in the project | + +3. Go to [OpenWeatherMap](https://openweathermap.org/) and sign up to obtain an API key. For details, see the [OpenWeatherMap documentation](https://openweathermap.org/appid#signup). + +## Step 1: Create a scheduled task component + +1. Go to [https://console.choreo.dev/](https://console.choreo.dev/) and sign in. This opens the project home page. +2. If you already have one or more components in your project, click **+ Create**. Otherwise, proceed to the next step. +3. Click the **Scheduled Task** card. +4. Click **Authorize with GitHub** to connect Choreo to your GitHub account. If you haven't connected your GitHub repository to Choreo, enter your credentials and select the repository you forked earlier to install the [Choreo GitHub App](https://github.com/marketplace/choreo-apps). + + Alternatively, select the **Use Public GitHub Repository** option and paste the [Choreo samples repository](https://github.com/wso2/choreo-samples) URL in the **Provide Repository URL** field. However, enabling [**Auto Deploy**](https://wso2.com/choreo/docs/choreo-concepts/ci-cd/#deploy) requires authorizing the repository with the [Choreo GitHub App](https://github.com/marketplace/choreo-apps). + + !!! note + The **Choreo GitHub App** requires: + - Read and write access to code and pull requests. + - Read access to issues and metadata. + + You can [revoke access](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/reviewing-your-authorized-integrations#reviewing-your-authorized-github-apps) at any time. Write access is only used for sending pull requests; Choreo will not push changes directly to your repository. + +5. Enter the following information: + + | **Field** | **Description** | + | --------------------- | ---------------------------------------------- | + | **Organization** | Your GitHub account | + | **Repository** | `choreo-samples` | + | **Branch** | `main` | + | **Component Directory** | `weather-to-email-scheduled-task` | + +6. Select **Ballerina** as the build pack. + + !!! tip + - **Buildpack** specifies the type of build to run depending on the implementation of the component. It converts the integration code into a Docker image that can run on Choreo cloud. If an integration is developed using [WSO2 Integration Studio](https://wso2.com/integration/integration-studio/), select **Micro Integrator** as the buildpack. If an integration is developed using the [Ballerina language](https://ballerina.io), select **Ballerina** as the buildpack. + - **Component Directory** specifies the location of the project to build the component. + +7. Enter a unique name and description for the component. You can use the following values: + + | **Field** | **Value** | + | ------------------ | -------------------------------- | + | **Component Name** | `WeatherToEmail` | + | **Description** | `My first scheduled task` | + +8. Click **Create**. Choreo initializes the component with the sample implementation and opens the **Overview** page of the component. + +Now you can proceed to build and deploy the scheduled task. + +## Step 2: Build the scheduled task + +1. In the left navigation menu, click **Build**. +2. In the **Builds** pane, click **Build**. This opens the **Commits** pane, where you can see all the commits related to the component. +3. Select the latest commit and click **Build**. This triggers the build process and displays the build progress in the **Build Logs** pane. + + !!! info + The build process may take some time. Once complete, the build status will be listed in the **Builds** pane. Here, you will see the build status as **Success**. + +## Step 3: Deploy the scheduled task + +1. In the left navigation menu, click **Deploy**. +2. In the **Set Up** card, click **Configure & Deploy**. +3. In the **Configurations** pane, specify values for the configurable variables: + + !!! tip + The configurable variables populated here are defined in the sample Ballerina project used in this guide. To learn how to declare configurable variables in Ballerina, see the [Ballerina documentation on declaring configurable variables](https://ballerina.io/learn/by-example/configurable-variables/). + + | **Field** | **Value** | + | ------------- | ----------------------------------------------------------------------- | + | **apiKey** | The API key you obtained in the prerequisites section | + | **latitude** | Latitude of the location to get the weather forecast | + | **longitude** | Longitude of the location to get the weather forecast | + | **email** | The email address to receive the formatted weather forecast information | + + !!! note + If you use **Ballerina** as the buildpack and want to set a configurable variable as a secret, click the lock icon corresponding to the configurable variable. This marks it as a secret and conceals the input value. + + For example, if you set the **apiKey** as a secret, its input value will be concealed. To update the input value later, click **Update Secret Content** and specify a new value. + +4. Click **Next**. +5. Define a schedule to run the task. In this guide, set the schedule to receive the weather information daily at 8:00 AM UTC. Enter the following values: + + | **Field** | **Value** | + | -------------------- | ----------------------------------------------------- | + | **Select Time Zone** | Select a time zone to schedule the task | + | **Select Range** | **Day** | + | **Every** | `1` | + | **At** | `08:00` | + + !!! tip + To test and verify the task immediately, you can schedule the deployment to run in just a few minutes after you create it. However, to avoid unnecessary expenses, reschedule or stop the deployment once you test and verify. + +6. Click **Deploy**. This deploys the scheduled task to the development environment and indicates the **Scheduled Status** as **Active** in the **Development** card. + +You can test the scheduled task when it runs at the configured time. + +## Step 4: Test the scheduled task + +When the scheduled task runs at the configured time, an email with the subject `[WSO2 Choreo Demo] Next 24H Weather Forecast` is sent from `choreo.demo@gmail.com` to the email address specified as the **email** configurable variable value in [Step 3](#step-3-deploy-the-scheduled-task). + +If the scheduled task ran successfully, you should receive an email similar to the following: + +![Received email](../../assets/img/develop-components/develop-a-scheduled-integration/Received-email.png) + +## Step 5: Observe the scheduled task + +The observability view in Choreo displays graphs that depict details such as throughput, latency, diagnostic data, and logs to identify and troubleshoot anomalies in components you deploy. + +1. In the left navigation menu, click **Observability**. +2. Observe the following: + - The throughput and latencies of requests served over a given period. + - The logs generated over a given period. + - The flame graph (Diagnostics View) generated over a given period. + - The low-code diagram. + +To learn more about the observability details you can view via Choreo observability, see [Observability Overview](../../monitoring-and-insights/observability-overview.md). + +## Step 6: Monitor executions + +To track and monitor executions associated with the deployed scheduled task, go to the left navigation menu and click **Execute**. + +!!! tip + The **Execute** view is applicable to both scheduled and manual tasks. + +You can view the following information: + +- **Total executions**: The total number of executions within the past 30 days. + + ![Total Execution](../../assets/img/develop-components/develop-a-scheduled-integration/total_executions.png) + +- **Execution history**: The currently active executions and those that are already complete. You can view information such as the execution ID, the revision of the execution, and the time it was triggered. + + ![Execution History](../../assets/img/develop-components/develop-a-scheduled-integration/execution_history.png) + +- **Detailed execution logs**: Click on an execution to view detailed logs related to it. + + !!! info + It may take a few minutes for the logs to appear. You may need to manually refresh to view the latest logs. + + ![Execution Logs](../../assets/img/develop-components/develop-a-scheduled-integration/execution_logs.png) diff --git a/en/developer-docs/docs/develop-components/develop-integrations/develop-an-event-handler.md b/en/developer-docs/docs/develop-components/develop-integrations/develop-an-event-handler.md new file mode 100644 index 000000000..77cac5c6a --- /dev/null +++ b/en/developer-docs/docs/develop-components/develop-integrations/develop-an-event-handler.md @@ -0,0 +1,100 @@ +# Develop an Event Handler + +An event handler executes predefined actions in response to specific events. Choreo simplifies the process of creating and deploying such integrations. + +This guide walks you through the steps to create and deploy an Event Handler using WSO2 MI and Choreo. + +In this guide, you will build a simple event handler that monitors RabbitMQ for new messages and displays them once they become available. + +## Prerequisites + +1. If you're signing in to the Choreo Console for the first time, create an organization: + 1. Go to [https://console.choreo.dev/](https://console.choreo.dev/) and sign in using your preferred method. + 2. Enter a unique organization name. For example, `Stark Industries`. + 3. Read and accept the privacy policy and terms of use. + 4. Click **Create**. + + This creates the organization and opens the **Project Home** page of the default project created for you. + +2. Set up RabbitMQ: + - Use an existing RabbitMQ instance or start a new [RabbitMQ](https://www.rabbitmq.com/download.html) instance on a server that can be accessed via the internet. + - Obtain the `username`, `hostname`, `password`, and `vhost` from the RabbitMQ instance to use later as environment variables. + +3. Fork the [Choreo samples repository](https://github.com/wso2/choreo-samples), which contains the sample integration for this guide. + +## Step 1: Create an event handler component + +1. Go to [https://console.choreo.dev/](https://console.choreo.dev/) and sign in. This opens the project home page. +2. If you already have one or more components in your project, click **+ Create**. Otherwise, proceed to the next step. +3. Click the **Event Handler** card. +4. Click **Authorize with GitHub** to connect Choreo to your GitHub account. If you haven't connected your GitHub repository to Choreo, enter your credentials and select the repository you forked earlier to install the [Choreo GitHub App](https://github.com/marketplace/choreo-apps). + + Alternatively, select the **Use Public GitHub Repository** option and paste the [Choreo samples repository](https://github.com/wso2/choreo-samples) URL in the **Provide Repository URL** field. However, enabling [**Auto Deploy**](https://wso2.com/choreo/docs/choreo-concepts/ci-cd/#deploy) requires authorizing the repository with the [Choreo GitHub App](https://github.com/marketplace/choreo-apps). + + !!! note + The **Choreo GitHub App** requires: + - Read and write access to code and pull requests. + - Read access to issues and metadata. + + You can [revoke access](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/reviewing-your-authorized-integrations#reviewing-your-authorized-github-apps) at any time. Write access is only used for sending pull requests; Choreo will not push changes directly to your repository. + +5. Enter the following information: + + | **Field** | **Description** | + |-----------------------|----------------------------- | + | **Organization** | Your GitHub account | + | **Repository** | `choreo-samples` | + | **Branch** | `main` | + | **Component Directory** | `mi-rabbitmq-listener` | + +6. Select **WSO2 MI** as the build pack. (since you are creating the REST API from a [WSO2 Integration Studio](https://wso2.com/micro-integrator/) project) + + !!! tip + - **Buildpack** specifies the type of build to run depending on the implementation of the component. It converts the integration code into a Docker image that can run on Choreo cloud. If an integration is developed using [WSO2 Integration Studio](https://wso2.com/integration/integration-studio/), select **Micro Integrator** as the buildpack. If an integration is developed using the [Ballerina language](https://ballerina.io), select **Ballerina** as the buildpack. + - **Component Directory** specifies the location of the project to build the component. + +7. Enter a unique name and description for the component. You can use the following values: + + | **Field** | **Value** | + |--------------------|------------------------| + | **Component Name** | `SalesOrderListener` | + | **Description** | `RabbitMQ integration` | + +8. Click **Create**. + +## Step 2: Deploy the integration + +1. In the left navigation menu, click **Deploy**. +2. In the **Build Area** card, click **Configure & Deploy**. +3. In the **Configurations** pane, click **+ Add** corresponding to **Environment Variables** and add the following environment variables: + + !!! tip + Use the values from your RabbitMQ instance as per the [Prerequisites](#prerequisites) section for the environment variables. + + | **Name** | **Value** | + | ------------- |--------------------------------------------------| + | **HOSTNAME** | Hostname of your RabbitMQ server | + | **VHOST** | Virtual hostname of your RabbitMQ server | + | **USERNAME** | Username for connecting to RabbitMQ | + | **PASSWORD** | Password associated with the RabbitMQ username | + +4. Click **Deploy**. This deploys the event handler to the development environment and indicates the **Deployment Status** as **Active** in the **Development** card. + +## Step 3: Test the integration + +1. Send a sales order message to the **SalesOrderQueue** on the RabbitMQ server. You can send a sample sales order message similar to the following: + + ```json + { + "order_id": "12345", + "customer_name": "John Doe", + "product": "Widget", + "quantity": 10, + "total_amount": 100.00 + } + ``` + +2. Observe the logs: + - In the left navigation menu, click **Logs** and then click **Runtime Logs**. You will see the order message in the logs. + +Now you have gained hands-on experience in creating, configuring, and deploying an event handler. diff --git a/en/developer-docs/docs/develop-components/develop-integrations/develop-an-integration-with-integration-studio.md b/en/developer-docs/docs/develop-components/develop-integrations/develop-an-integration-with-integration-studio.md new file mode 100644 index 000000000..2b5ed863a --- /dev/null +++ b/en/developer-docs/docs/develop-components/develop-integrations/develop-an-integration-with-integration-studio.md @@ -0,0 +1,105 @@ +# Develop an Integration with Integration Studio + +Choreo simplifies the process of building, deploying, and managing integration components, making it easy to expose integrations as APIs. This guide walks you through the steps to expose an integration created in WSO2 Integration Studio as an API in Choreo. + +In this guide, you will: +- Create a component to expose a sample integration from the [Choreo samples repository](https://github.com/wso2/choreo-samples) as an API. +- Deploy, test, and observe the integration component. +- Publish the integration component as an API to the Choreo Developer Portal. + +!!! note + - To develop integrations for **Manual Task** and **Schedule Task** components in Choreo, use the **automation mode** in the WSO2 Micro Integrator. See [Running MI in Automation Mode](https://apim.docs.wso2.com/en/4.2.0/install-and-setup/install/running-the-mi-in-automation-mode/). + - For other component types (Service, webhook, event-handler, etc.), use the **server mode**. + +## Prerequisites + +1. If you're signing in to the Choreo Console for the first time, create an organization: + - Go to [https://console.choreo.dev/](https://console.choreo.dev/) and sign in. + - Enter a unique organization name. For example, `Stark Industries`. + - Read and accept the privacy policy and terms of use. + - Click **Create**. This creates the organization and opens the **Project Home** page. + +2. Fork the [Choreo samples repository](https://github.com/wso2/choreo-samples), which contains the sample integration for this guide. + +## Step 1: Create the integration component + +1. Go to [https://console.choreo.dev/](https://console.choreo.dev/) and sign in. This opens the **Project Home** page. + +2. If you already have one or more components in your project, click **+ Create**. Otherwise, proceed to the next step. +3. Click the **Service** card. +4. Click **Authorize with GitHub** to connect your GitHub account. If you haven't connected your GitHub repository to Choreo, enter your GitHub credentials and select the repository you forked in the prerequisites section to install the [Choreo GitHub App](https://github.com/marketplace/choreo-apps). + + !!! note + The **Choreo GitHub App** requires the following permissions: + - Read and write access to code and pull requests. + - Read access to issues and metadata. + + You can [revoke access](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/reviewing-your-authorized-integrations#reviewing-your-authorized-github-apps) if needed. Write access is only used for sending pull requests; Choreo will not push changes directly to your repository. + +5. Enter the following repository details: + + | **Field** | **Description** | + |-----------------------|----------------------------- | + | **Organization** | Your GitHub account | + | **Repository** | `choreo-samples` | + | **Branch** | **`main`** | + | **Component Directory** | `hello-world-mi` | + +6. Select WSO2 MI as the build pack (since you're creating the REST API from a [WSO2 Integration Studio](https://wso2.com/micro-integrator/) project). + +7. Provide a unique name and description for the component: + + | **Field** | **Value** | + |--------------------|------------------------| + | **Component Name** | `Hello World` | + | **Description** | `Hello World REST API` | + +8. Click **Create**. Choreo initializes the component with the sample integration. + +## Step 2: Deploy the integration component + +1. In the Choreo Console left navigation menu, click **Deploy**. + +2. Configure and deploy: + - In the **Build Area** card, click **Configure & Deploy**. + - In the **Configurations** pane, click **Next**. This displays the endpoint details ready for deployment. + - Click **Deploy**. This deploys the integration component to the development environment. + + !!! tip + - Choreo uses [endpoints](../../choreo-concepts/endpoint.md) to expose **Service** components to the network. Learn more about configuring endpoints in [Configure Endpoints](../configure-endpoints.md). + - Automatic deployment is enabled by default, so only the first deployment needs to be done manually. + + The **Development** card shows the **Deployment Status** as **Active** when the integration is successfully deployed. + +## Step 3: Test the integration + +1. In the Choreo Console left navigation menu, click **Test** and then click **Console**. +2. In the OpenAPI Console, select **Development** from the environment drop-down list. +3. Expand the **GET /integration** operation. +4. Click **Try it out**, then click **Execute**. This sends a request to your deployed integration. +5. Check the response: + - In the **Response body** section, observe the response. If the integration works as expected, you should see: + + ```json + {"Hello" : "Integration"} + ``` + +## Step 4: Observe the integration + +1. Click **Observability** in the left navigation menu to monitor the performance of the integration component. + +2. View metrics: + - Observe throughput and latencies of requests over time. + - View logs generated during a specific period. + - Analyze the flame graph (Diagnostics View) for performance insights. + + For more details, see [Observability Overview](../../monitoring-and-insights/observability-overview.md). + +## Step 5: Publish the integration component + +1. In the Choreo Console left navigation menu, click **Manage** and then click **Lifecycle**. +2. The **Lifecycle Management** pane shows the current lifecycle stage as **Created**. +3. Click **Publish**. This changes the lifecycle stage to **Published** and exposes the integration as an API in the Choreo Developer Portal. + - To view the published API, click **Go to Devportal**. In the Developer Portal, you can manage subscriptions and generate access tokens for testing. + +Now you have successfully exposed an integration designed in WSO2 Integration Studio as a REST API in Choreo! diff --git a/en/developer-docs/docs/develop-components/develop-proxy/develop-an-api-proxy-from-a-github-repository-source.md b/en/developer-docs/docs/develop-components/develop-proxy/develop-an-api-proxy-from-a-github-repository-source.md new file mode 100644 index 000000000..1e545d351 --- /dev/null +++ b/en/developer-docs/docs/develop-components/develop-proxy/develop-an-api-proxy-from-a-github-repository-source.md @@ -0,0 +1,162 @@ +# Develop an API Proxy from a GitHub Repository Source + +An API proxy acts as an intermediary between an existing API and Choreo, intercepting all requests made to the API. It also functions as a managed API, allowing you to apply essential API management features such as security policies and rate limiting. + +In this guide, you will: + +- Create an API proxy component to expose an existing API. +- Deploy the API proxy. +- Test the API proxy to verify its functionality. +- Manage the API. +- Consume the API. + +## Prerequisites + +1. If you're signing in to the Choreo Console for the first time, create an organization: + 1. Go to [https://console.choreo.dev/](https://console.choreo.dev/) and sign in using your preferred method. + 2. Enter a unique organization name. For example, `Stark Industries`. + 3. Read and accept the privacy policy and terms of use. + 4. Click **Create**. + + This creates the organization and opens the **Project Home** page of the default project created for you. + +2. Fork the [Choreo samples repository](https://github.com/wso2/choreo-samples/), which contains the [sample proxy source](https://github.com/wso2/choreo-samples/tree/main/department-api-proxy-from-github). + +## Step 1: Create an API proxy + +You can create an API proxy either by selecting the source from a GitHub repository, uploading an OpenAPI specification file, or providing an OpenAPI specification URL. This guide demonstrates how to create an API proxy using a GitHub repository as the source. + +1. Go to [https://console.choreo.dev/](https://console.choreo.dev/) and sign in. This opens the project home page. +2. If you already have one or more components in your project, click **+ Create**. Otherwise, proceed to the next step. +3. Click the **API Proxy** card. This opens the **Create an API Proxy** pane. + +4. Click on **Authorize With GitHub** card under **Connect a Git Repository** section to connect your GitHub account. + - If you haven’t connected your GitHub repository to Choreo, enter your GitHub credentials and select the repository you forked in the prerequisites section to install the [Choreo GitHub App](https://github.com/marketplace/choreo-apps). + + !!! note + The **Choreo GitHub App** requires the following permissions: + - Read and write access to code and pull requests. + - Read access to issues and metadata. + + You can [revoke access](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/reviewing-your-authorized-integrations#reviewing-your-authorized-github-apps) if needed. Write access is only used for sending pull requests; Choreo will not push changes directly to your repository. + +5. Enter the following repository details: + + | **Field** | **Value** | + |------------------------|--------------------| + | **Organization** | Your GitHub account| + | **Repository** | choreo-samples | + | **Branch** | **`main`** | + | **API Directory** | /department-api-proxy-from-github | + + !!! note + To select the relevant directory, click on the **Edit** action next to the **API Directory** input field. Then, enter `department-api-proxy-from-github` as the directory name to quickly search and locate the correct directory. + +6. Specify the following values as Proxy Metadata: + + !!! info + The **Context** field must be unique and cannot be changed after creation.**Version** and **Target** are mandatory fields. **Target** can be changed at any time after the creation. + + | **Field** | **Value** | + |-----------------|--------------------------------------------| + | **Context** | `department-service` | + | **Version** | `v1.0` | + | **Target** | `https://samples.choreoapps.dev/company/hr`| + +7. Specify the following values as Component Details: + + !!! info + The **Component Name** field must be unique and cannot be changed after creation. This value is automatically generated, but you can edit it if necessary. + **Component Display Name** is a required field. + + | **Field** | **Value** | + |-----------------|--------------------------------------------| + | **Component Display Name**| `Department Service` | + | **Component Name** | `department-service` | + | **Description** | `This is a sample proxy for department service` | + +8. Click **Create**. This creates the API proxy component and takes you to the **Build** page. + +!!! note + When you create an API proxy from a GitHub repository source, the GitHub source serves as the single source of truth. Therefore, any modifications, such as adding or deleting resources, must be made through the GitHub repository. + +## Step 2: Build + +!!! info + The initial build starts automatically when you create the API proxy, and you will be redirected to the **Build** page. In this case, you can skip the steps below. If you need to manually trigger a build later, follow these steps. + +1. On the project home page, click on the `Department Service` component you created. This takes you to the component overview page. +2. In the left navigation menu, click **Build**. +3. On the **Build** page, click **Build Latest**. + +!!! note + The build process may take some time. You can track progress in the **Build Details** pane. Once complete, the build status changes to **Success**. + +## Step 3: Deploy the API proxy + +1. In the left navigation menu, click **Deploy**. +2. In the **Build Area** card, click **Configure & Deploy**. This opens the **Configure & Deploy** pane. +3. Select **External** as the **API Access Mode** and click **Deploy**. The **Development** card indicates the **Deployment Status** as **Active** when the API proxy is successfully deployed. + +Now you are ready to test the API proxy. + +## Step 4: Test the API proxy + +Choreo allows you to test your API proxy using either the [integrated OpenAPI Console](../../testing/test-rest-endpoints-via-the-openapi-console.md) or [cURL](../../testing/test-apis-with-curl.md). In this guide, you will use the OpenAPI Console. + +!!! tip + Choreo enables OAuth 2.0 to secure APIs by default. Therefore, you need an access token to invoke an API. + + - Choreo automatically generates a key to test the API via the OpenAPI Console. To view the key, click the show key icon in the **Security Header** field. + - To disable security for the entire API or a specific resource: + 1. In the left navigation menu, click **Deploy**. + 2. Go to the **Build Area** card and click **Security Settings**. + 3. In the **Security Settings** pane: + - To disable security for the entire API, clear the **OAuth2** checkbox. + - To disable security for a specific resource, expand the relevant resource and turn off the **Security** toggle. + 4. Click **Apply**. + +1. In the left navigation menu, click **Test** and then click **OpenAPI Console**. +2. Select **Development** from the environment drop-down list. +3. Expand the `GET /department/{departmentId}` resource and click **Try it Out**. +4. Enter `1` as the **departmentId** and click **Execute**. You will see a response similar to the following: + + ![API proxy response](../../assets/img/develop-components/develop-a-rest-api-proxy/rest-api-proxy-response.png){.cInlineImage-full} + + This indicates that your API proxy is working as expected. + +## Step 5: Manage the API proxy + +Now that you have a tested API proxy, you can publish it and make it available for application developers to consume. In this guide, you will apply rate limiting to the API and publish it. + +### Step 5.1: Apply rate limiting to the API proxy + +1. In the left navigation menu, click **Deploy**. +2. Go to the required environment card and click the settings icon corresponding to **API Configuration**. +3. In the **CORS, Rate Limiting and Resiliency** pane, click **Rate Limiting** to expand the section. +4. Select **API Level** as the **Rate Limiting Level**. +5. Specify appropriate values for the **Request Limit** and **Time Unit** fields. You can proceed with the default values. +6. Click **Apply**. This applies the rate limiting level to the API proxy and redeploys it. + +### Step 5.2: Publish the API proxy + +1. In the left navigation menu, click **Lifecycle** under **Manage**. This takes you to the **Lifecycle** page. +2. Click **Publish**. +3. In the **Publish API** dialog, click **Confirm** to proceed with publishing the API. If you want to change the display name, make the necessary changes and then click **Confirm**. This changes the API lifecycle state to **Published**. + +## Step 6: Invoke the API + +To generate credentials for the published API and invoke it via the Choreo Developer Portal, follow these steps: + +1. In the **Lifecycle** page, click **Go to Devportal**. This takes you to the `Department Service` in the Choreo Developer Portal. + +2. **Invoke the API**: + 1. In the Developer Portal left navigation menu, click **Try Out**. + 2. In the **Endpoint** list, select **Development** as the environment to try out the API. + 3. Click **Get Test Key** to generate an access token. + 4. Expand the `GET /department/{departmentId}` resource and click **Try it out**. + 5. Enter `1` as the **departmentId** and click **Execute**. You will see a response similar to the following: + + ![Try out response](../../assets/img/develop-components/develop-a-rest-api-proxy/try-out-response.png){.cInlineImage-full} + +Now, you have gained hands-on experience creating, deploying, testing, and publishing an API proxy using Choreo. diff --git a/en/developer-docs/docs/develop-components/develop-proxy/develop-an-api-proxy-from-scratch.md b/en/developer-docs/docs/develop-components/develop-proxy/develop-an-api-proxy-from-scratch.md new file mode 100644 index 000000000..7f3c08500 --- /dev/null +++ b/en/developer-docs/docs/develop-components/develop-proxy/develop-an-api-proxy-from-scratch.md @@ -0,0 +1,136 @@ +# Develop an API Proxy from Scratch + +An API proxy acts as an intermediary between an existing API and Choreo, intercepting all requests made to the API. It also functions as a managed API, allowing you to apply essential API management features such as security policies and rate limiting. + +In this guide, you will: + +- Create an API proxy component to expose an existing API. +- Deploy the API proxy. +- Test the API proxy to verify its functionality. +- Manage the API. +- Consume the API. + +## Prerequisites + +- If you're signing in to the Choreo Console for the first time, create an organization: + 1. Go to [https://console.choreo.dev/](https://console.choreo.dev/) and sign in using your preferred method. + 2. Enter a unique organization name. For example, `Stark Industries`. + 3. Read and accept the privacy policy and terms of use. + 4. Click **Create**. + + This creates the organization and opens the **Project Home** page of the default project created for you. + +## Step 1: Create an API proxy + +To create an API proxy, you can either upload an OpenAPI specification or provide an OpenAPI specification URL. In this guide, you will specify a URL to an OpenAPI definition of a sample API. + +1. Go to [https://console.choreo.dev/](https://console.choreo.dev/) and sign in. This opens the project home page. +2. If you already have one or more components in your project, click **+ Create**. Otherwise, proceed to the next step. +3. Click the **API Proxy** card. This opens the **Create an API Proxy** pane. +4. Select **Creare from Scratch** option. +5. Specify the following values as Proxy Metadata: + + | **Field** | **Value** | + |-----------------|--------------------------------------------| + | **Context** | `department-service` | + | **Version** | `v1.0` | + | **Target** | `https://samples.choreoapps.dev/company/hr` | + +6. Enter following details for the Component Details: + + !!! info + The **Component Name** field must be unique and cannot be changed after creation. + + | **Field** | **Value** | + |---------------------------|--------------------| + | **Component Display Name**| `Department Service` | + | **Component Name** | `department-service` | + | **Description** | `Sample proxy for department service` | + +7. Click **Create**. This creates the API proxy component and takes you to the **Deploy** page. + +## Step 2: Define resources for the API proxy + +To add a new resource that retrieves a department by the department ID, follow these steps: + +1. In the left navigation menu, click **Develop** and then click **Resources**. +2. Select **GET** as the **HTTP Verb** and enter `/department/{departmentId}` as the **URI Pattern**. +3. Click **+** to add the resource. +4. Expand the added resource and specify the following values: + + | **Field** | **Value** | + |------------------|--------------------------------------| + | **Operation ID** | `findDepartment` | + | **Description** | `Find a department by department ID` | + +5. Remove the five default resources that start with `/*` by clicking the delete icon corresponding to each resource. +6. Click **Save**. + +## Step 3: Deploy the API proxy + +1. In the left navigation menu, click **Deploy**. +2. In the **Build Area** card, click **Configure & Deploy**. This opens the **Configure & Deploy** pane. +3. Select **External** as the API access mode and click **Deploy**. The **Development** card indicates the **Deployment Status** as **Active** when the API proxy is successfully deployed. + +Now you are ready to test the API proxy. + +## Step 4: Test the API proxy + +Choreo allows you to test your API proxy using either the [integrated OpenAPI Console](../../testing/test-rest-endpoints-via-the-openapi-console.md) or [cURL](../../testing/test-apis-with-curl.md). In this guide, you will use the OpenAPI Console. + +!!! tip + Choreo enables OAuth 2.0 to secure APIs by default. Therefore, you need an access token to invoke an API. + + - Choreo automatically generates a key to test the API via the OpenAPI Console. To view the key, click the show key icon in the **Security Header** field. + - To disable security for the entire API or a specific resource: + 1. In the left navigation menu, click **Deploy**. + 2. Go to the **Build Area** card and click **Security Settings**. + 3. In the **Security Settings** pane: + - To disable security for the entire API, clear the **OAuth2** checkbox. + - To disable security for a specific resource, expand the relevant resource and turn off the **Security** toggle. + 4. Click **Apply**. + +1. In the left navigation menu, click **Test** and then click **OpenAPI Console**. +2. Select **Development** from the environment drop-down list. +3. Expand the `GET /department/{departmentId}` resource and click **Try it Out**. +4. Enter `1` as the **departmentId** and click **Execute**. You will see a response similar to the following: + + ![API proxy response](../../assets/img/develop-components/develop-a-rest-api-proxy/rest-api-proxy-response.png){.cInlineImage-full} + + This indicates that your API proxy is working as expected. + +## Step 5: Manage the API proxy + +Now that you have a tested API proxy, you can publish it and make it available for application developers to consume. In this guide, you will apply rate limiting to the API and publish it. + +### Step 5.1: Apply rate limiting to the API proxy + +1. In the left navigation menu, click **Deploy**. +2. Go to the required environment card and click the settings icon corresponding to **CORS, Rate Limiting and Resiliency**. +3. In the **CORS, Rate Limiting and Resiliency** pane, click **Rate Limiting** to expand the section. +4. Select **API Level** as the **Rate Limiting Level**. +5. Specify appropriate values for the **Request Limit** and **Time Unit** fields. You can proceed with the default values. +6. Click **Apply**. This applies the rate limiting level to the API proxy and redeploys it. + +### Step 5.2: Publish the API proxy + +1. In the left navigation menu, click **Lifecycle** under **Manage**. This takes you to the **Lifecycle** page. +2. Click **Publish**. +3. In the **Publish API** dialog, click **Confirm** to proceed with publishing the API. If you want to change the display name, make the necessary changes and then click **Confirm**. This changes the API lifecycle state to **Published**. + +## Step 6: Invoke the API + +To generate credentials for the published API and invoke it via the Choreo Developer Portal, follow these steps: + +1. In the **Lifecycle** page, click **Go to Devportal**. This takes you to the `Department Service` in the Choreo Developer Portal. + +2. **Invoke the API**: + 1. In the Developer Portal left navigation menu, click **Try Out**. + 2. In the **Endpoint** list, select **Development** as the environment to try out the API. + 3. Click **Get Test Key** to generate an access token. + 4. Expand the `GET /department/{departmentId}` resource and click **Try it out**. + 5. Enter `1` as the **departmentId** and click **Execute**. You will see a response similar to the following: + + ![Try out response](../../assets/img/develop-components/develop-a-rest-api-proxy/try-out-response.png){.cInlineImage-full} + +Now, you have gained hands-on experience creating, deploying, testing, and publishing an API proxy using Choreo. \ No newline at end of file diff --git a/en/developer-docs/docs/develop-components/develop-services/develop-a-ballerina-service.md b/en/developer-docs/docs/develop-components/develop-services/develop-a-ballerina-service.md new file mode 100644 index 000000000..9e19f1342 --- /dev/null +++ b/en/developer-docs/docs/develop-components/develop-services/develop-a-ballerina-service.md @@ -0,0 +1,117 @@ +# Develop a Ballerina Service + +Choreo allows you to develop and deploy applications using your preferred programming language. This guide demonstrates how to deploy a service component that exposes a REST API using the [Ballerina language](https://ballerina.io/). No prior knowledge of Ballerina is required to follow this guide. + +A REST API is a web service that adheres to Representational State Transfer (REST) principles, using HTTP methods to access and manage resources. This guide walks you through building a Ballerina service component, deploying it on Choreo, and testing it with an HTTP client application. + +In this guide, you will: + + - Build a simple greeting service using a sample implementation. The service has a single resource named `greet` that accepts a query parameter as input. + - Deploy the service in Choreo. + - Test the service. + +## Prerequisites + +1. If you're signing in to the Choreo Console for the first time, create an organization: + - Go to [https://console.choreo.dev/](https://console.choreo.dev/) and sign in. + - Enter a unique organization name. For example, `Stark Industries`. + - Read and accept the privacy policy and terms of use. + - Click **Create**. This creates the organization and opens the **Project Home** page. + +2. Fork the [Choreo samples repository](https://github.com/wso2/choreo-samples/), which contains the [sample greetings service](https://github.com/wso2/choreo-samples/tree/main/greeting-service) implementation in Ballerina. + +### Learn the repository file structure + +It’s important to understand the purpose of key files in the sample service. The table below provides an overview of each file in the greeter service: + +!!! note + The file paths are relative to `/greeting-service`. + +| **Filepath** | **Description** | +|---------------------------|---------------------------------------------------------------| +| `service.bal` | The greetings service code written in Ballerina. | +| `tests/service_test.bal` | Test files related to the `service.bal` file. | +| `Ballerina.toml` | The Ballerina configuration file. | + +Let’s get started! + +## Step 1: Create a service component + +To create a Ballerina service component, follow these steps: + +1. Go to [https://console.choreo.dev/](https://console.choreo.dev/) and sign in. This opens the **Project Home** page. +2. If you already have one or more components in your project, click **+ Create**. Otherwise, proceed to the next step. +3. Click the **Service** card. +4. Click **Authorize with GitHub** to connect your GitHub account. If you haven’t connected your GitHub repository to Choreo, enter your GitHub credentials and select the repository you forked in the prerequisites section to install the [Choreo GitHub App](https://github.com/marketplace/choreo-apps). + + !!! note + The **Choreo GitHub App** requires the following permissions: + - Read and write access to code and pull requests. + - Read access to issues and metadata. + + You can [revoke access](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/reviewing-your-authorized-integrations#reviewing-your-authorized-github-apps) if needed. Write access is only used for sending pull requests; Choreo will not push changes directly to your repository. + +5. Provide the following repository details: + + | **Field** | **Value** | + |------------------------|--------------------| + | **Organization** | Your GitHub account| + | **Repository** | choreo-samples | + | **Branch** | **`main`** | + |**Component Directory** | `/greeting-service` | + +6. Select **Ballerina** as the buildpack. + +7. Provide a display name, a unique name, and a description for the service component: + + !!! info + The **Component Name** field specifies a unique identifier for the component. This name cannot be changed after creation. + + | **Field** | **Value** | + |---------------------------|-------------------------| + | **Component Display Name**| `Ballerina Greetings` | + | **Component Name** | `ballerina-greetings` | + | **Description** | Send greetings | + +8. Click **Create**. This creates the component and takes you to the **Overview** page. + +You have successfully created a service that exposes a REST API written in Ballerina. Next, let’s build and deploy the service. + +## Step 2: Build and deploy + +Now that you’ve connected the source repository and configured the endpoint details, it’s time to build and deploy the service. + +!!! note + If you’re rebuilding the Ballerina service component after changing the Ballerina version, ensure that the version in the `Ballerina.toml` file matches the version in the `Dependencies.toml` file. + +### Step 2.1: Build + +To build the service, follow these steps: + +1. In the left navigation menu, click **Build**. +2. On the **Build** page, click **Build Latest**. + + !!! note + Building the service may take a while. Track the progress via the logs in the **Build Details** pane. Once complete, the build status changes to **Success**. + +### Step 2.2: Deploy + +To deploy the service, follow these steps: + +1. In the left navigation menu, click **Deploy**. +2. On the **Set Up** card, click **Configure & Deploy**. +3. In the **Configurations** pane, click **Next** to skip the configuration. +4. Review the **Endpoint Details** and click **Deploy**. + + !!! note + Deploying the service may take a while. Once deployed, the **Development** environment card shows the **Deployment Status** as **Active**. + +Once deployed, you can test, manage, and observe the service like any other component in Choreo. + +For detailed instructions, see the following sections: +- [Step 3: Test](../../testing/test-rest-endpoints-via-the-openapi-console.md) +- [Step 4: Manage](../../api-management/lifecycle-management.md) + +## Manage the deployment + +To view Kubernetes-level insights for detailed diagnosis of this Ballerina REST API, see Choreo’s [DevOps capabilities](../../devops-and-ci-cd/view-runtime-details.md). diff --git a/en/developer-docs/docs/develop-components/develop-services/develop-a-service-with-docker.md b/en/developer-docs/docs/develop-components/develop-services/develop-a-service-with-docker.md new file mode 100644 index 000000000..ddcf4dd7e --- /dev/null +++ b/en/developer-docs/docs/develop-components/develop-services/develop-a-service-with-docker.md @@ -0,0 +1,133 @@ +# Develop a Service with Docker + +Choreo allows you to create and deploy applications in any language. This guide demonstrates how to develop and deploy a containerized service component using a Dockerfile. + +In this guide, you will: + + - Create a containerized service component using a sample service implementation. The sample service has a single resource named `greet` that accepts a query parameter as input. + - Deploy the service in Choreo using a Dockerfile. The service will run on port 9090. + - Test the service. + +If you want to create a service component that exposes a Ballerina service, see [Develop a Ballerina Service](develop-a-ballerina-service.md). + +## Prerequisites + +1. If you're signing in to the Choreo Console for the first time, create an organization: + - Go to [https://console.choreo.dev/](https://console.choreo.dev/) and sign in. + - Enter a unique organization name. For example, `Stark Industries`. + - Read and accept the privacy policy and terms of use. + - Click **Create**. This creates the organization and opens the **Project Home** page. + +2. Fork the [Choreo samples repository](https://github.com/wso2/choreo-samples/), which contains the [sample greetings service](https://github.com/wso2/choreo-samples/tree/main/greeting-service-go) implementation with the Dockerfile. + +### Learn the repository file structure + +It’s important to understand the purpose of key files in the sample service. The table below provides an overview of each file in the greeter service: + +!!! note + The file paths are relative to `/greeting-service-go`. + +| **Filepath** | **Description** | +|----------------------------|------------------------------------------------------------------------------| +| `main.go` | The Go-based greeter service code. | +| `Dockerfile` | The Dockerfile to build the container image of the application. | +| `.choreo/component.yaml` | Choreo-specific configuration that provides information about how Choreo exposes the service. | +| `openapi.yaml` | The OpenAPI contract of the greeter service. This is required to publish the service as a managed API. This file is referenced by the `.choreo/component.yaml` file. | + +### Configure the service port with endpoints + +In Choreo, you can expose your services via endpoints. The greeter service runs on port 9090. To securely expose the service through Choreo, you must provide the port and other required information in the `component.yaml` file. For detailed information on each attribute of an endpoint, see [Configure Endpoints](../configure-endpoints.md). + +In the greeter sample, the `component.yaml` file is located in the `greeting-service-go/.choreo/` directory. + +## Step 1: Create a service component from a Dockerfile + +To create a containerized service component, follow these steps: + +1. Go to [https://console.choreo.dev/](https://console.choreo.dev/cloud-native-app-developer) and sign in. This opens the **Project Home** page. +2. If you already have one or more components in your project, click **+ Create**. Otherwise, proceed to the next step. +3. Click the **Service** card. +4. Click **Authorize with GitHub** to connect your GitHub account. If you haven’t connected your GitHub repository to Choreo, enter your GitHub credentials and select the repository you forked in the prerequisites section to install the [Choreo GitHub App](https://github.com/marketplace/choreo-apps). + + !!! note + The **Choreo GitHub App** requires the following permissions: + - Read and write access to code and pull requests. + - Read access to issues and metadata. + + You can [revoke access](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/reviewing-your-authorized-integrations#reviewing-your-authorized-github-apps) if needed. Write access is only used for sending pull requests; Choreo will not push changes directly to your repository. + +5. Enter the following repository details: + + | **Field** | **Value** | + |------------------------|--------------------| + | **Organization** | Your GitHub account| + | **Repository** | choreo-samples | + | **Branch** | `main` | + | **Component Directory** | `/greeting-service-go` | + +6. Select **Docker** as the buildpack. +7. Enter the following details: + + | **Field** | **Value** | + |--------------------------|----------------------------------| + | **Dockerfile** | `/greeting-service-go/Dockerfile`| + + !!! info + 1. To successfully build your container with Choreo, explicitly define a user ID (UID) under the `USER` instruction in your Dockerfile. For reference, see the [sample Dockerfile](https://github.com/wso2/choreo-sample-apps/blob/main/go/greeter/Dockerfile). + - A valid User ID is a numeric value between 10000-20000 (e.g., `10001` or `10500`). + - Usernames are invalid and should not be used (e.g., `my-custom-user-12221` or `my-custom-user`). + + 2. The Dockerfile used in this guide is a multi-stage Dockerfile, which keeps the final image size small and allows building the application with specific versions of tools and libraries. + +8. Provide a display name, a unique name, and a description for the service component: + + !!! info + The **Component Name** field specifies a unique identifier for the component. This name cannot be changed after creation. + + | **Field** | **Value** | + |---------------------------|--------------------| + | **Component Display Name**| `Greetings` | + | **Component Name** | `greetings` | + | **Description** | Send greetings | + +9. Click **Create**. This creates the component and takes you to the **Overview** page. + +You have successfully created a service from a Dockerfile. Next, you can build and deploy the service. + +## Step 2: Build and deploy + +Now that you’ve connected the source repository and configured the endpoint details, it’s time to build the service and create an image. Then, you can deploy the image and test the greeter service. + +### Step 2.1: Build + +To build the service, follow these steps: + +1. In the left navigation menu, click **Build**. +2. On the **Build** page, click **Build Latest**. + + !!! note + Building the service may take a while. Track the progress via the logs in the **Build Details** pane. Once complete, the build status changes to **Success**. + + You can access the following scans under **Build**: + - **Dockerfile Scan**: Choreo checks if a non-root user ID is assigned to the Docker container for security. If no non-root user is specified, the build will fail. + - **Container (Trivy) Vulnerability Scan**: This detects vulnerabilities in the final Docker image. If critical vulnerabilities are found, the build will fail. + + !!! info + If you have Choreo environments on a private data plane, you can ignore these vulnerabilities and proceed with the deployment. + +### Step 2.2: Deploy + +To deploy the service, follow these steps: + +1. In the left navigation menu, click **Deploy**. +2. On the **Set Up** card, click **Configure & Deploy**. +3. In the **Environment Configurations** pane, click **Next** to skip the configuration. +4. In the **File Mount** pane, click **Next** to skip the configuration. +5. Review the **Endpoint Details** and click **Deploy**. + + !!! note + Deploying the service may take a while. Once deployed, the **Development** environment card shows the **Deployment Status** as **Active**. + +Once deployed, you can [test](../../testing/test-rest-endpoints-via-the-openapi-console.md), [manage](../../api-management/lifecycle-management.md), and [observe](../../monitoring-and-insights/observability-overview.md) the service like any other component in Choreo. + +To view Kubernetes-level insights for detailed diagnosis of this Dockerfile-based REST API, see [Choreo's DevOps capabilities](../../devops-and-ci-cd/view-runtime-details.md). diff --git a/en/developer-docs/docs/develop-components/develop-services/develop-a-service.md b/en/developer-docs/docs/develop-components/develop-services/develop-a-service.md new file mode 100644 index 000000000..28fe90ab6 --- /dev/null +++ b/en/developer-docs/docs/develop-components/develop-services/develop-a-service.md @@ -0,0 +1,115 @@ +# Develop a Service + +Choreo allows you to create and deploy applications in your preferred programming language. + +In this guide, you will: + +- Build a simple greeting service using a sample service implementation. The sample implementation will have a single resource named `greet` that accepts a single query parameter as input. +- Deploy the service in Choreo using a `Go` buildpack. The service will run on port 9090. +- Test the service. + +## Prerequisites + +1. If you're signing in to the Choreo Console for the first time, create an organization: + 1. Go to [https://console.choreo.dev/](https://console.choreo.dev/) and sign in using your preferred method. + 2. Enter a unique organization name. For example, `Stark Industries`. + 3. Read and accept the privacy policy and terms of use. + 4. Click **Create**. + + This creates the organization and opens the **Project Home** page of the default project created for you. + +2. Fork the [Choreo samples repository](https://github.com/wso2/choreo-samples/), which contains the [sample greetings service](https://github.com/wso2/choreo-samples/tree/main/greeting-service-go) implementation in `Go`. + +### Learn the repository file structure + +It is important to understand the purpose of the key files in the sample service. The following table provides a brief overview of each file in the greeter service: + +!!! note + The specified file paths are relative to `/greeting-service-go`. + +| **Filepath** | **Description** | +|--------------------------|-------------------------------------------------------------------------------| +| `main.go` | The Go-based greeter service code. | +| `.choreo/component.yaml` | Choreo-specific configuration that provides information about how Choreo exposes the service. | +| `openapi.yaml` | The OpenAPI contract of the greeter service. This is required to publish the service as a managed API. This `openapi.yaml` file is referenced by the `.choreo/component.yaml` file. | + +### Configure the service port with endpoints + +In Choreo, you can expose your services via endpoints. To run the greeter service on port 9090 and securely expose it through Choreo, you must provide the port and other required information in the `component.yaml` file. For detailed information on each attribute of an endpoint, see [Configure Endpoints](../configure-endpoints.md). + +In the greeter sample, the `component.yaml` file is located in the `greeting-service-go/.choreo/` directory. + +## Step 1: Create a service component + +To create a containerized service component, follow these steps: + +1. Go to [https://console.choreo.dev/](https://console.choreo.dev/) and sign in. This opens the project home page. +2. If you already have one or more components in your project, click **+ Create**. Otherwise, proceed to the next step. +3. Click the **Service** card. +4. Click **Authorize with GitHub** to connect Choreo to your GitHub account. If you haven't connected your GitHub repository to Choreo, enter your credentials and select the repository you forked earlier to install the [Choreo GitHub App](https://github.com/marketplace/choreo-apps). + + Alternatively, select the **Use Public GitHub Repository** option and paste the [Choreo samples repository](https://github.com/wso2/choreo-samples) URL in the **Public Repository URL** field. However, enabling [**Auto Deploy**](https://wso2.com/choreo/docs/choreo-concepts/ci-cd/#deploy) requires authorizing the repository with the [Choreo GitHub App](https://github.com/marketplace/choreo-apps). + + !!! note + The **Choreo GitHub App** requires: + - Read and write access to code and pull requests. + - Read access to issues and metadata. + + You can [revoke access](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/reviewing-your-authorized-integrations#reviewing-your-authorized-github-apps) at any time. Write access is only used for sending pull requests; Choreo will not push changes directly to your repository. + +5. Under **Connect a Git Repository**, enter the following details: + + | **Field** | **Value** | + |------------------------|--------------------| + | **Organization** | Your GitHub account| + | **GitHub Repository** | choreo-samples | + | **Branch** | main | + | **Component Directory** | `/greeting-service-go` | + +6. Select **Go** as the buildpack. +7. Enter the following details: + + | **Field** | **Value** | + |--------------------------|------------------------| + | **Language Version** | 1.x | + +8. Provide component display name, name and description: + + !!! info + The **Component Name** field must be unique and cannot be changed after creation. + + | **Field** | **Value** | + |---------------------------|--------------------| + | **Component Display Name**| Greetings | + | **Component Name** | greetings | + | **Description** | Send greetings | + +9. Click **Create**. This creates the component and lists it under **Component Listing** on the project home page. + +You have successfully created the service. The next step is to build and deploy it. + +## Step 2: Build and deploy + +Now that you have connected the source repository and configured the endpoint details, it's time to build and deploy the greeter service. + +### Step 2.1: Build + +1. On the project home page, click on the `Greetings` component you created. This takes you to the component overview page. +2. In the left navigation menu, click **Build**. +3. On the **Build** page, click **Build Latest**. + + !!! note + The build process may take some time. You can track progress in the **Build Details** pane. Once complete, the build status changes to **Success**. + +### Step 2.2: Deploy + +1. In the left navigation menu, click **Deploy**. +2. On the **Set Up** card, click **Configure & Deploy**. +3. In the **Environment Configurations** pane, click **Next** to skip the configuration. +4. In the **File Mount** pane, click **Next** to skip the configuration. +5. Review the **Endpoint Details** and click **Deploy**. + + !!! note + Deploying the service component may take some time. Once deployed, the **Development** environment card indicates the **Deployment Status** as **Active**. + +Once you have successfully deployed the service, you can [test](../../testing/test-rest-endpoints-via-the-openapi-console.md), [manage](../../api-management/lifecycle-management.md), and [observe](../../monitoring-and-insights/observability-overview.md) it like any other component type in Choreo. diff --git a/en/docs/develop-components/develop-services/expose-a-ballerina-graphql-endpoint-via-a-service.md b/en/developer-docs/docs/develop-components/develop-services/expose-a-ballerina-graphql-endpoint-via-a-service.md similarity index 89% rename from en/docs/develop-components/develop-services/expose-a-ballerina-graphql-endpoint-via-a-service.md rename to en/developer-docs/docs/develop-components/develop-services/expose-a-ballerina-graphql-endpoint-via-a-service.md index b964335d7..c33278aa9 100644 --- a/en/docs/develop-components/develop-services/expose-a-ballerina-graphql-endpoint-via-a-service.md +++ b/en/developer-docs/docs/develop-components/develop-services/expose-a-ballerina-graphql-endpoint-via-a-service.md @@ -170,21 +170,9 @@ To create a Ballerina service component, follow these steps: 1. Go to [https://console.choreo.dev/](https://console.choreo.dev/) and sign in. This opens the project home page. 2. If you already have one or more components in your project, click **+ Create**. Otherwise, proceed to the next step. 3. Click the **Service** card. -4. Enter a display name, a unique name, and a description for the service component. You can enter the values given below: - - !!! info - In the **Component Name** field, you must specify a name to uniquely identify the component in various contexts. The value is editable only at the time you create the component. You cannot change the name after you create the component. - - | **Field** | **Value** | - |---------------------------|-------------------------| - | **Component Display Name**| `Ballerina Reading List`| - | **Component Name** | `ballerina-reading-list`| - | **Description** | Manage a reading list | - -5. Click the **GitHub** tab. -6. To allow Choreo to connect to your GitHub account, click **Authorize with GitHub**. If you have not already connected your GitHub repository to Choreo, enter your GitHub credentials and select the repository you created in the prerequisites section to install the [Choreo GitHub App](https://github.com/marketplace/choreo-apps). +4. To allow Choreo to connect to your GitHub account, click **Authorize with GitHub**. If you have not already connected your GitHub repository to Choreo, enter your GitHub credentials and select the repository you created in the prerequisites section to install the [Choreo GitHub App](https://github.com/marketplace/choreo-apps). - Alternatively, you can paste the [Choreo samples repository](https://github.com/wso2/choreo-samples) URL in the **Provide Repository URL** field to connect to it without requiring authorization from the [Choreo Apps](https://github.com/marketplace/choreo-apps) GitHub application. However, authorizing the repository with the [Choreo GitHub App](https://github.com/marketplace/choreo-apps) is necessary if you want to enable [**Auto Deploy**](https://wso2.com/choreo/docs/choreo-concepts/ci-cd/#deploy) for the component. + Alternatively, select the **Use Public GitHub Repository** option and paste the [Choreo samples repository](https://github.com/wso2/choreo-samples) URL in the **Provide Repository URL** field to connect to it without requiring authorization from the [Choreo Apps](https://github.com/marketplace/choreo-apps) GitHub application. However, authorizing the repository with the [Choreo GitHub App](https://github.com/marketplace/choreo-apps) is necessary if you want to enable [**Auto Deploy**](https://wso2.com/choreo/docs/choreo-concepts/ci-cd/#deploy) for the component. !!! note The **Choreo GitHub App** requires the following permissions: @@ -194,22 +182,29 @@ To create a Ballerina service component, follow these steps: You can [revoke access](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/reviewing-your-authorized-integrations#reviewing-your-authorized-github-apps) if you do not want Choreo to have access to your GitHub account. However, write access is exclusively utilized for sending pull requests to a user repository. Choreo will not directly push any changes to a repository. -7. Under **Connect Your Repository**, enter the following information: +5. Under **Connect a Git Repository**, enter the following information: | **Field** | **Value** | |-------------------------|-------------------------| | **Organization** | Your GitHub account | | **GitHub Repository** | **`choreo-samples`** | | **Branch** | **`main`** | + | **Component Directory**| `reading-list-graphql` |. -8. Select **Ballerina** as the buildpack. -9. Enter the following information: +6. Select **Ballerina** as the buildpack. + +7. Enter a display name, a unique name, and a description for the service component. You can enter the values given below: - | **Field** | **Value** | - |--------------------------------|---------------------------| - | **Ballerina Project Directory**| `reading-list-graphql` |. + !!! info + In the **Component Name** field, you must specify a name to uniquely identify the component in various contexts. The value is editable only at the time you create the component. You cannot change the name after you create the component. + + | **Field** | **Value** | + |---------------------------|-------------------------| + | **Component Display Name**| `Ballerina Reading List`| + | **Component Name** | `ballerina-reading-list`| + | **Description** | Manage a reading list | -10. Click **Create**. This creates the component and takes you to the **Overview** page of the component. +8. Click **Create**. This creates the component and takes you to the **Overview** page of the component. You have successfully created a service component that exposes a GraphQL API written in the Ballerina language. Next, let's build and deploy the service. diff --git a/en/docs/develop-components/develop-services/expose-a-grpc-endpoint-via-a-service.md b/en/developer-docs/docs/develop-components/develop-services/expose-a-grpc-endpoint-via-a-service.md similarity index 89% rename from en/docs/develop-components/develop-services/expose-a-grpc-endpoint-via-a-service.md rename to en/developer-docs/docs/develop-components/develop-services/expose-a-grpc-endpoint-via-a-service.md index b7c7e5c1a..64c5beefb 100644 --- a/en/docs/develop-components/develop-services/expose-a-grpc-endpoint-via-a-service.md +++ b/en/developer-docs/docs/develop-components/develop-services/expose-a-grpc-endpoint-via-a-service.md @@ -83,21 +83,9 @@ To create a containerized service component, follow these steps: 1. Go to [https://console.choreo.dev/](https://console.choreo.dev/) and sign in. This opens the project home page. 2. If you already have one or more components in your project, click **+ Create**. Otherwise, proceed to the next step. 3. Click the **Service** card. -4. Enter a display name, a unique name, and a description for the service component. You can enter the values given below: - - !!! info - In the **Component Name** field, you must specify a name to uniquely identify the component in various contexts. The value is editable only at the time you create the component. You cannot change the name after you create the component. - - | **Field** | **Value** | - |---------------------------|-------------------------| - | **Component Display Name**| `Go gRPC Server` | - | **Component Name** | `go-grpc-server` | - | **Description** | Send greetings | - -5. Click the **GitHub** tab. 6. To allow Choreo to connect to your GitHub account, click **Authorize with GitHub**. If you have not already connected your GitHub repository to Choreo, enter your GitHub credentials and select the repository you created in the prerequisites section to install the [Choreo GitHub App](https://github.com/marketplace/choreo-apps). - Alternatively, you can paste the [Choreo samples repository](https://github.com/wso2/choreo-samples) URL in the **Provide Repository URL** field to connect to it without requiring authorization from the [Choreo Apps](https://github.com/marketplace/choreo-apps) GitHub application. However, authorizing the repository with the [Choreo GitHub App](https://github.com/marketplace/choreo-apps) is necessary if you want to enable [**Auto Deploy**](https://wso2.com/choreo/docs/choreo-concepts/ci-cd/#deploy) for the component. + Alternatively, select the **Use Public GitHub Repository** option and paste the [Choreo samples repository](https://github.com/wso2/choreo-samples) URL in the **Provide Repository URL** field to connect to it without requiring authorization from the [Choreo Apps](https://github.com/marketplace/choreo-apps) GitHub application. However, authorizing the repository with the [Choreo GitHub App](https://github.com/marketplace/choreo-apps) is necessary if you want to enable [**Auto Deploy**](https://wso2.com/choreo/docs/choreo-concepts/ci-cd/#deploy) for the component. !!! note The **Choreo GitHub App** requires the following permissions: @@ -107,20 +95,20 @@ To create a containerized service component, follow these steps: You can [revoke access](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/reviewing-your-authorized-integrations#reviewing-your-authorized-github-apps) if you do not want Choreo to have access to your GitHub account. However, write access is exclusively utilized for sending pull requests to a user repository. Choreo will not directly push any changes to a repository. -7. Under **Connect Your Repository**, enter the following information: +7. Under **Connect a Git Repository**, enter the following information: | **Field** | **Value** | |-------------------------|-------------------------| | **Organization** | Your GitHub account | | **GitHub Repository** | **`choreo-samples`** | | **Branch** | **`main`** | + | **Component Directory** | `go-grpc` | 8. Select **Docker** as the buildpack. 9. Enter the following information: | **Field** | **Value** | |--------------------------|----------------------------| - | **Docker Context** | `go-grpc` | | **Dockerfile** | `go-grpc/Dockerfile.server`| !!! info @@ -131,6 +119,17 @@ To create a containerized service component, follow these steps: 2. The Dockerfile utilized in this guide is a multi-stage Dockerfile, which is designed to keep the final image size small and provides the ability to build the application with a specific version of tools and libraries. +4. Enter a display name, a unique name, and a description for the service component. You can enter the values given below: + + !!! info + In the **Component Name** field, you must specify a name to uniquely identify the component in various contexts. The value is editable only at the time you create the component. You cannot change the name after you create the component. + + | **Field** | **Value** | + |---------------------------|-------------------------| + | **Component Display Name**| `Go gRPC Server` | + | **Component Name** | `go-grpc-server` | + | **Description** | Send greetings | + 10. Click **Create**. This creates the component and takes you to the **Overview** page of the component. You have successfully created a service from a Dockerfile. Next, you can build and deploy the service. @@ -186,21 +185,9 @@ To create a manual task component, follow these steps: 1. On the Choreo Console header, click the **Project** list and select the project where you created the gRPC service component. This opens the project home page. 2. Go to the **Component Listing** section and click **+ Create**. 3. Click the **Manual Task** card. -4. Enter a display name, a unique name, and a description for the component. You can enter the values given below: - - !!! info - In the **Component Name** field, you must specify a name to uniquely identify the component in various contexts. The value is editable only at the time you create the component. You cannot change the name after you create the component. - - | **Field** | **Value** | - |---------------------------|-------------------------| - | **Component Display Name**| `Go gRPC Client` | - | **Component Name** | `go-grpc-client` | - | **Description** | `Receive greetings` | - -5. Click the **GitHub** tab. -6. To allow Choreo to connect to your GitHub account, click **Authorize with GitHub**. If you have not already connected your GitHub repository to Choreo, enter your GitHub credentials and select the repository you created in the prerequisites section to install the [Choreo GitHub App](https://github.com/marketplace/choreo-apps). +4. To allow Choreo to connect to your GitHub account, click **Authorize with GitHub**. If you have not already connected your GitHub repository to Choreo, enter your GitHub credentials and select the repository you created in the prerequisites section to install the [Choreo GitHub App](https://github.com/marketplace/choreo-apps). - Alternatively, you can paste the [Choreo samples repository](https://github.com/wso2/choreo-samples) URL in the **Provide Repository URL** field to connect to it without requiring authorization from the [Choreo Apps](https://github.com/marketplace/choreo-apps) GitHub application. However, authorizing the repository with the [Choreo GitHub App](https://github.com/marketplace/choreo-apps) is necessary if you want to enable [**Auto Deploy**](https://wso2.com/choreo/docs/choreo-concepts/ci-cd/#deploy) for the component. + Alternatively, select the **Use Public GitHub Repository** option and paste the [Choreo samples repository](https://github.com/wso2/choreo-samples) URL in the **Provide Repository URL** field to connect to it without requiring authorization from the [Choreo Apps](https://github.com/marketplace/choreo-apps) GitHub application. However, authorizing the repository with the [Choreo GitHub App](https://github.com/marketplace/choreo-apps) is necessary if you want to enable [**Auto Deploy**](https://wso2.com/choreo/docs/choreo-concepts/ci-cd/#deploy) for the component. !!! note The **Choreo GitHub App** requires the following permissions: @@ -210,23 +197,35 @@ To create a manual task component, follow these steps: You can [revoke access](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/reviewing-your-authorized-integrations#reviewing-your-authorized-github-apps) if you do not want Choreo to have access to your GitHub account. However, write access is exclusively utilized for sending pull requests to a user repository. Choreo will not directly push any changes to a repository. -7. Under **Connect Your Repository**, enter the following information: +5. Under **Connect a Git Repository**, enter the following information: | **Field** | **Value** | |-------------------------|-------------------------| | **Organization** | Your GitHub account | | **GitHub Repository** | **`choreo-samples`** | | **Branch** | **`main`** | + | **Component Directory** | `go/grpc` | -8. Select **Docker** as the buildpack. -9. Enter the following information: +6. Select **Docker** as the buildpack. +7. Enter the following information: | **Field** | **Value** | |--------------------------|----------------------------| - | **Docker Context** | `go/grpc` | | **Dockerfile** | `go/grpc/Dockerfile.client`| -10. Click **Create**. This creates the component and takes you to the **Overview** page of the component. +8. Enter a display name, a unique name, and a description for the component. You can enter the values given below: + + !!! info + In the **Component Name** field, you must specify a name to uniquely identify the component in various contexts. The value is editable only at the time you create the component. You cannot change the name after you create the component. + + | **Field** | **Value** | + |---------------------------|-------------------------| + | **Component Display Name**| `Go gRPC Client` | + | **Component Name** | `go-grpc-client` | + | **Description** | `Receive greetings` | + + +9. Click **Create**. This creates the component and takes you to the **Overview** page of the component. ### Step 3.2: Build the gRPC client component diff --git a/en/docs/develop-components/develop-services/expose-a-prism-based-mock-server-using-an-openapi-specification.md b/en/developer-docs/docs/develop-components/develop-services/expose-a-prism-based-mock-server-using-an-openapi-specification.md similarity index 92% rename from en/docs/develop-components/develop-services/expose-a-prism-based-mock-server-using-an-openapi-specification.md rename to en/developer-docs/docs/develop-components/develop-services/expose-a-prism-based-mock-server-using-an-openapi-specification.md index 1e94b004a..08d81cf66 100644 --- a/en/docs/develop-components/develop-services/expose-a-prism-based-mock-server-using-an-openapi-specification.md +++ b/en/developer-docs/docs/develop-components/develop-services/expose-a-prism-based-mock-server-using-an-openapi-specification.md @@ -26,13 +26,7 @@ To create a Prism mock service component, follow these steps: 1. Go to [https://console.choreo.dev/](https://console.choreo.dev/) and sign in. This opens the project home page. 2. If you already have one or more components in your project, click **+ Create**. Otherwise, proceed to the next step. 3. Click the **Service** card. -4. Enter a display name, a unique name, and a description for the service component. - - !!! info - In the **Component Name** field, you must specify a name to uniquely identify the component in various contexts. The value is editable only at the time you create the component. You cannot change the name after you create the component. - -5. Click the **GitHub** tab. -6. To allow Choreo to connect to your GitHub account, click **Authorize with GitHub**. If you have not already connected your GitHub repository to Choreo, enter your GitHub credentials and select the repository you created in the prerequisites section to install the [Choreo GitHub App](https://github.com/marketplace/choreo-apps). +4. To allow Choreo to connect to your GitHub account, click **Authorize with GitHub**. If you have not already connected your GitHub repository to Choreo, enter your GitHub credentials and select the repository you created in the prerequisites section to install the [Choreo GitHub App](https://github.com/marketplace/choreo-apps). Alternatively, you can paste the [Choreo samples repository](https://github.com/wso2/choreo-samples) URL in the **Provide Repository URL** field to connect to it without requiring authorization from the [Choreo Apps](https://github.com/marketplace/choreo-apps) GitHub application. However, authorizing the repository with the [Choreo GitHub App](https://github.com/marketplace/choreo-apps) is necessary if you want to enable [**Auto Deploy**](https://wso2.com/choreo/docs/choreo-concepts/ci-cd/#deploy) for the component. @@ -44,17 +38,22 @@ To create a Prism mock service component, follow these steps: You can [revoke access](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/reviewing-your-authorized-integrations#reviewing-your-authorized-github-apps) if you do not want Choreo to have access to your GitHub account. However, write access is exclusively utilized for sending pull requests to a user repository. Choreo will not directly push any changes to a repository. -7. Under **Connect Your Repository**, enter the following information: +5. Under **Connect a Git Repository**, enter the following information: | **Field** | **Value** | |-------------------------|-------------------------| | **Organization** | Your GitHub account | | **GitHub Repository** | **`choreo-samples`** | | **Branch** | **`main`** | + |**Component Directory** | `prism-mock-service` | + +6. Select **Prism Mock** as the buildpack. +7. Enter a display name, a unique name, and a description for the service component. + + !!! info + In the **Component Name** field, you must specify a name to uniquely identify the component in various contexts. The value is editable only at the time you create the component. You cannot change the name after you create the component. -8. Select **Prism Mock** as the buildpack. -9. Select `prism-mock-service` as the **Project Directory**. -10. Click **Create**. This creates the component and takes you to the **Overview** page of the component. +8. Click **Create**. This creates the component and takes you to the **Overview** page of the component. ## Step 2: Build and deploy the component diff --git a/en/docs/develop-components/develop-services/expose-a-tcp-server-via-a-service.md b/en/developer-docs/docs/develop-components/develop-services/expose-a-tcp-server-via-a-service.md similarity index 87% rename from en/docs/develop-components/develop-services/expose-a-tcp-server-via-a-service.md rename to en/developer-docs/docs/develop-components/develop-services/expose-a-tcp-server-via-a-service.md index 39cfce1c0..f1702167e 100644 --- a/en/docs/develop-components/develop-services/expose-a-tcp-server-via-a-service.md +++ b/en/developer-docs/docs/develop-components/develop-services/expose-a-tcp-server-via-a-service.md @@ -65,21 +65,9 @@ To create a containerized service component, follow these steps: 1. Go to [https://console.choreo.dev/](https://console.choreo.dev/) and sign in. This opens the project home page. 2. If you already have one or more components in your project, click **+ Create**. Otherwise, proceed to the next step. 3. Click the **Service** card. -4. Enter a display name, a unique name, and a description for the service component. You can enter the values given below: - - !!! info - In the **Component Name** field, you must specify a name to uniquely identify the component in various contexts. The value is editable only at the time you create the component. You cannot change the name after you create the component. +4. To allow Choreo to connect to your GitHub account, click **Authorize with GitHub**. If you have not already connected your GitHub repository to Choreo, enter your GitHub credentials and select the repository you created in the prerequisites section to install the [Choreo GitHub App](https://github.com/marketplace/choreo-apps). - | **Field** | **Value** | - |---------------------------|-------------------------| - | **Component Display Name**| `Go TCP Server` | - | **Component Name** | `go-tcp-server` | - | **Description** | Send greetings | - -5. Click the **GitHub** tab. -6. To allow Choreo to connect to your GitHub account, click **Authorize with GitHub**. If you have not already connected your GitHub repository to Choreo, enter your GitHub credentials and select the repository you created in the prerequisites section to install the [Choreo GitHub App](https://github.com/marketplace/choreo-apps). - - Alternatively, you can paste the [Choreo samples repository](https://github.com/wso2/choreo-samples) URL in the **Provide Repository URL** field to connect to it without requiring authorization from the [Choreo Apps](https://github.com/marketplace/choreo-apps) GitHub application. However, authorizing the repository with the [Choreo GitHub App](https://github.com/marketplace/choreo-apps) is necessary if you want to enable [**Auto Deploy**](https://wso2.com/choreo/docs/choreo-concepts/ci-cd/#deploy) for the component. + Alternatively, select the **Use Public GitHub Repository** option and paste the [Choreo samples repository](https://github.com/wso2/choreo-samples) URL in the **Provide Repository URL** field to connect to it without requiring authorization from the [Choreo Apps](https://github.com/marketplace/choreo-apps) GitHub application. However, authorizing the repository with the [Choreo GitHub App](https://github.com/marketplace/choreo-apps) is necessary if you want to enable [**Auto Deploy**](https://wso2.com/choreo/docs/choreo-concepts/ci-cd/#deploy) for the component. !!! note The **Choreo GitHub App** requires the following permissions: @@ -89,20 +77,20 @@ To create a containerized service component, follow these steps: You can [revoke access](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/reviewing-your-authorized-integrations#reviewing-your-authorized-github-apps) if you do not want Choreo to have access to your GitHub account. However, write access is exclusively utilized for sending pull requests to a user repository. Choreo will not directly push any changes to a repository. -7. Under **Connect Your Repository**, enter the following information: +5. Under **Connect a Git Repository**, enter the following information: | **Field** | **Value** | |-------------------------|-------------------------| | **Organization** | Your GitHub account | | **GitHub Repository** | **`choreo-samples`** | | **Branch** | **`main`** | + | **Component Directory** | `docker-tcp-service` | -8. Select **Docker** as the buildpack. -9. Enter the following information: +6. Select **Docker** as the buildpack. +7. Enter the following information: | **Field** | **Value** | |--------------------------|---------------------------------------| - | **Docker Context** | `docker-tcp-service` | | **Dockerfile** | `docker-tcp-service/Dockerfile.server`| !!! info @@ -113,7 +101,18 @@ To create a containerized service component, follow these steps: 2. The Dockerfile utilized in this guide is a multi-stage Dockerfile, which is designed to keep the final image size small and provides the ability to build the application with a specific version of tools and libraries. -10. Click **Create**. This creates the component and takes you to the **Overview** page of the component. +8. Enter a display name, a unique name, and a description for the service component. You can enter the values given below: + + !!! info + In the **Component Name** field, you must specify a name to uniquely identify the component in various contexts. The value is editable only at the time you create the component. You cannot change the name after you create the component. + + | **Field** | **Value** | + |---------------------------|-------------------------| + | **Component Display Name**| `Go TCP Server` | + | **Component Name** | `go-tcp-server` | + | **Description** | Send greetings | + +9. Click **Create**. This creates the component and takes you to the **Overview** page of the component. You have successfully created a service from a Dockerfile. Next, you can build and deploy the service. @@ -168,21 +167,9 @@ To create a manual task component, follow these steps: 1. On the Choreo Console header, click the **Project** list and select the project where you created the TCP service component. This opens the project home page. 2. Go to the **Component Listing** section and click **+ Create**. 3. Click the **Manual Task** card. -4. Enter a display name, a unique name, and a description for the component. You can enter the values given below: - - !!! info - In the **Component Name** field, you must specify a name to uniquely identify the component in various contexts. The value is editable only at the time you create the component. You cannot change the name after you create the component. - - | **Field** | **Value** | - |---------------------------|------------------------| - | **Component Display Name**| `Go TCP Client` | - | **Component Name** | `go-tcp-client` | - | **Description** | `Receive greetings` | +4. To allow Choreo to connect to your GitHub account, click **Authorize with GitHub**. If you have not already connected your GitHub repository to Choreo, enter your GitHub credentials and select the repository you created in the prerequisites section to install the [Choreo GitHub App](https://github.com/marketplace/choreo-apps). -5. Click the **GitHub** tab. -6. To allow Choreo to connect to your GitHub account, click **Authorize with GitHub**. If you have not already connected your GitHub repository to Choreo, enter your GitHub credentials and select the repository you created in the prerequisites section to install the [Choreo GitHub App](https://github.com/marketplace/choreo-apps). - - Alternatively, you can paste the [Choreo samples repository](https://github.com/wso2/choreo-samples) URL in the **Provide Repository URL** field to connect to it without requiring authorization from the [Choreo Apps](https://github.com/marketplace/choreo-apps) GitHub application. However, authorizing the repository with the [Choreo GitHub App](https://github.com/marketplace/choreo-apps) is necessary if you want to enable [**Auto Deploy**](https://wso2.com/choreo/docs/choreo-concepts/ci-cd/#deploy) for the component. + Alternatively, select the **Use Public GitHub Repository** option and paste the [Choreo samples repository](https://github.com/wso2/choreo-samples) URL in the **Provide Repository URL** field to connect to it without requiring authorization from the [Choreo Apps](https://github.com/marketplace/choreo-apps) GitHub application. However, authorizing the repository with the [Choreo GitHub App](https://github.com/marketplace/choreo-apps) is necessary if you want to enable [**Auto Deploy**](https://wso2.com/choreo/docs/choreo-concepts/ci-cd/#deploy) for the component. !!! note The **Choreo GitHub App** requires the following permissions: @@ -192,23 +179,35 @@ To create a manual task component, follow these steps: You can [revoke access](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/reviewing-your-authorized-integrations#reviewing-your-authorized-github-apps) if you do not want Choreo to have access to your GitHub account. However, write access is exclusively utilized for sending pull requests to a user repository. Choreo will not directly push any changes to a repository. -7. Under **Connect Your Repository**, enter the following information: +5. Under **Connect a Git Repository**, enter the following information: | **Field** | **Value** | |-------------------------|-------------------------| | **Organization** | Your GitHub account | | **GitHub Repository** | **`choreo-samples`** | | **Branch** | **`main`** | + | **Docker Context** |`docker-tcp-service` | -8. Select **Docker** as the buildpack. -9. Enter the following information: +6. Select **Docker** as the buildpack. +7. Enter the following information: | **Field** | **Value** | |--------------------------|---------------------------------------| - | **Docker Context** | `docker-tcp-service` | | **Dockerfile** | `docker-tcp-service/Dockerfile.client`| -10. Click **Create**. This creates the component and takes you to the **Overview** page of the component. +8. Enter a display name, a unique name, and a description for the component. You can enter the values given below: + + !!! info + In the **Component Name** field, you must specify a name to uniquely identify the component in various contexts. The value is editable only at the time you create the component. You cannot change the name after you create the component. + + | **Field** | **Value** | + |---------------------------|------------------------| + | **Component Display Name**| `Go TCP Client` | + | **Component Name** | `go-tcp-client` | + | **Description** | `Receive greetings` | + + +9. Click **Create**. This creates the component and takes you to the **Overview** page of the component. ### Step 3.2: Build the TCP client component diff --git a/en/docs/develop-components/develop-services/expose-a-udp-server-via-a-service.md b/en/developer-docs/docs/develop-components/develop-services/expose-a-udp-server-via-a-service.md similarity index 89% rename from en/docs/develop-components/develop-services/expose-a-udp-server-via-a-service.md rename to en/developer-docs/docs/develop-components/develop-services/expose-a-udp-server-via-a-service.md index 93df9cc9f..178bddded 100644 --- a/en/docs/develop-components/develop-services/expose-a-udp-server-via-a-service.md +++ b/en/developer-docs/docs/develop-components/develop-services/expose-a-udp-server-via-a-service.md @@ -65,21 +65,9 @@ To create a containerized service component, follow these steps: 1. Go to [https://console.choreo.dev/](https://console.choreo.dev/) and sign in. This opens the project home page. 2. If you already have one or more components in your project, click **+ Create**. Otherwise, proceed to the next step. 3. Click the **Service** card. -4. Enter a display name, a unique name, and a description for the service component. You can enter the values given below: - - !!! info - In the **Component Name** field, you must specify a name to uniquely identify the component in various contexts. The value is editable only at the time you create the component. You cannot change the name after you create the component. - - | **Field** | **Value** | - |---------------------------|-------------------------| - | **Component Display Name**| `Go UDP Server` | - | **Component Name** | `go-udp-server` | - | **Description** | Send greetings | - -5. Click the **GitHub** tab. 6. To allow Choreo to connect to your GitHub account, click **Authorize with GitHub**. If you have not already connected your GitHub repository to Choreo, enter your GitHub credentials and select the repository you created in the prerequisites section to install the [Choreo GitHub App](https://github.com/marketplace/choreo-apps). - Alternatively, you can paste the [Choreo samples repository](https://github.com/wso2/choreo-samples) URL in the **Provide Repository URL** field to connect to it without requiring authorization from the [Choreo Apps](https://github.com/marketplace/choreo-apps) GitHub application. However, authorizing the repository with the [Choreo GitHub App](https://github.com/marketplace/choreo-apps) is necessary if you want to enable [**Auto Deploy**](https://wso2.com/choreo/docs/choreo-concepts/ci-cd/#deploy) for the component. + Alternatively, select the **Use Public GitHub Repository** option and paste the [Choreo samples repository](https://github.com/wso2/choreo-samples) URL in the **Provide Repository URL** field to connect to it without requiring authorization from the [Choreo Apps](https://github.com/marketplace/choreo-apps) GitHub application. However, authorizing the repository with the [Choreo GitHub App](https://github.com/marketplace/choreo-apps) is necessary if you want to enable [**Auto Deploy**](https://wso2.com/choreo/docs/choreo-concepts/ci-cd/#deploy) for the component. !!! note The **Choreo GitHub App** requires the following permissions: @@ -89,20 +77,20 @@ To create a containerized service component, follow these steps: You can [revoke access](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/reviewing-your-authorized-integrations#reviewing-your-authorized-github-apps) if you do not want Choreo to have access to your GitHub account. However, write access is exclusively utilized for sending pull requests to a user repository. Choreo will not directly push any changes to a repository. -7. Under **Connect Your Repository**, enter the following information: +7. Under **Connect a Git Repository**, enter the following information: | **Field** | **Value** | |-------------------------|-------------------------| | **Organization** | Your GitHub account | | **GitHub Repository** | **`choreo-samples`** | | **Branch** | **`main`** | + | **Component Directory** | `docker-udp-service` | 8. Select **Docker** as the buildpack. 9. Enter the following information: | **Field** | **Value** | |--------------------------|---------------------------------------| - | **Docker Context** | `docker-udp-service` | | **Dockerfile** | `docker-udp-service/Dockerfile.server`| !!! info @@ -113,6 +101,17 @@ To create a containerized service component, follow these steps: 2. The Dockerfile utilized in this guide is a multi-stage Dockerfile, which is designed to keep the final image size small and provides the ability to build the application with a specific version of tools and libraries. +4. Enter a display name, a unique name, and a description for the service component. You can enter the values given below: + + !!! info + In the **Component Name** field, you must specify a name to uniquely identify the component in various contexts. The value is editable only at the time you create the component. You cannot change the name after you create the component. + + | **Field** | **Value** | + |---------------------------|-------------------------| + | **Component Display Name**| `Go UDP Server` | + | **Component Name** | `go-udp-server` | + | **Description** | Send greetings | + 10. Click **Create**. This creates the component and takes you to the **Overview** page of the component. You have successfully created a service from a Dockerfile. Next, you can build and deploy the service. @@ -168,21 +167,9 @@ To create a manual task component, follow these steps: 1. On the Choreo Console header, click the **Project** list and select the project where you created the UDP service component. This opens the project home page. 2. Go to the **Component Listing** section and click **+ Create**. 3. Click the **Manual Task** card. -4. Enter a display name, a unique name, and a description for the component. You can enter the values given below: - - !!! info - In the **Component Name** field, you must specify a name to uniquely identify the component in various contexts. The value is editable only at the time you create the component. You cannot change the name after you create the component. - - | **Field** | **Value** | - |---------------------------|------------------------| - | **Component Display Name**| `Go UDP Client` | - | **Component Name** | `go-udp-client` | - | **Description** | `Receive greetings` | - -5. Click the **GitHub** tab. -6. To allow Choreo to connect to your GitHub account, click **Authorize with GitHub**. If you have not already connected your GitHub repository to Choreo, enter your GitHub credentials and select the repository you created in the prerequisites section to install the [Choreo GitHub App](https://github.com/marketplace/choreo-apps). +4. To allow Choreo to connect to your GitHub account, click **Authorize with GitHub**. If you have not already connected your GitHub repository to Choreo, enter your GitHub credentials and select the repository you created in the prerequisites section to install the [Choreo GitHub App](https://github.com/marketplace/choreo-apps). - Alternatively, you can paste the [Choreo samples repository](https://github.com/wso2/choreo-samples) URL in the **Provide Repository URL** field to connect to it without requiring authorization from the [Choreo Apps](https://github.com/marketplace/choreo-apps) GitHub application. However, authorizing the repository with the [Choreo GitHub App](https://github.com/marketplace/choreo-apps) is necessary if you want to enable [**Auto Deploy**](https://wso2.com/choreo/docs/choreo-concepts/ci-cd/#deploy) for the component. + Alternatively, select the **Use Public GitHub Repository** option and paste the [Choreo samples repository](https://github.com/wso2/choreo-samples) URL in the **Provide Repository URL** field to connect to it without requiring authorization from the [Choreo Apps](https://github.com/marketplace/choreo-apps) GitHub application. However, authorizing the repository with the [Choreo GitHub App](https://github.com/marketplace/choreo-apps) is necessary if you want to enable [**Auto Deploy**](https://wso2.com/choreo/docs/choreo-concepts/ci-cd/#deploy) for the component. !!! note The **Choreo GitHub App** requires the following permissions: @@ -192,23 +179,35 @@ To create a manual task component, follow these steps: You can [revoke access](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/reviewing-your-authorized-integrations#reviewing-your-authorized-github-apps) if you do not want Choreo to have access to your GitHub account. However, write access is exclusively utilized for sending pull requests to a user repository. Choreo will not directly push any changes to a repository. -7. Under **Connect Your Repository**, enter the following information: +5. Under **Connect a Git Repository**, enter the following information: | **Field** | **Value** | |-------------------------|-------------------------| | **Organization** | Your GitHub account | | **GitHub Repository** | **`choreo-samples`** | | **Branch** | **`main`** | + | **Component Directory** | `docker-udp-service` | -8. Select **Docker** as the buildpack. -9. Enter the following information: +6. Select **Docker** as the buildpack. +7. Enter the following information: | **Field** | **Value** | |--------------------------|---------------------------------------| - | **Docker Context** | `docker-udp-service` | | **Dockerfile** | `docker-udp-service/Dockerfile.client`| -10. Click **Create**. This creates the component and takes you to the **Overview** page of the component. +8. Enter a display name, a unique name, and a description for the component. You can enter the values given below: + + !!! info + In the **Component Name** field, you must specify a name to uniquely identify the component in various contexts. The value is editable only at the time you create the component. You cannot change the name after you create the component. + + | **Field** | **Value** | + |---------------------------|------------------------| + | **Component Display Name**| `Go UDP Client` | + | **Component Name** | `go-udp-client` | + | **Description** | `Receive greetings` | + + +9. Click **Create**. This creates the component and takes you to the **Overview** page of the component. ### Step 3.2: Build the UDP client component diff --git a/en/docs/develop-components/develop-services/expose-a-websocket-endpoint-via-a-service.md b/en/developer-docs/docs/develop-components/develop-services/expose-a-websocket-endpoint-via-a-service.md similarity index 84% rename from en/docs/develop-components/develop-services/expose-a-websocket-endpoint-via-a-service.md rename to en/developer-docs/docs/develop-components/develop-services/expose-a-websocket-endpoint-via-a-service.md index 7e3c6ff7d..62b1a9496 100644 --- a/en/docs/develop-components/develop-services/expose-a-websocket-endpoint-via-a-service.md +++ b/en/developer-docs/docs/develop-components/develop-services/expose-a-websocket-endpoint-via-a-service.md @@ -46,21 +46,9 @@ To create a NodeJS service component, follow these steps: 1. Go to [https://console.choreo.dev/](https://console.choreo.dev/) and sign in. This opens the project home page. 2. If you already have one or more components in your project, click **+ Create**. Otherwise, proceed to the next step. 3. Click the **Service** card. -4. Enter a display name, a unique name, and a description for the service component. You can enter the values given below: +4. To allow Choreo to connect to your GitHub account, click **Authorize with GitHub**. If you have not already connected your GitHub repository to Choreo, enter your GitHub credentials and select the repository you created in the prerequisites section to install the [Choreo GitHub App](https://github.com/marketplace/choreo-apps). - !!! info - In the **Component Name** field, you must specify a name to uniquely identify the component in various contexts. The value is editable only at the time you create the component. You cannot change the name after you create the component. - - | **Field** | **Value** | - |---------------------------|-------------------------| - | **Component Display Name**| `NodeJS Chat Service` | - | **Component Name** | `nodejs-chat-service` | - | **Description** | Manage a chat service | - -5. Click the **GitHub** tab. -6. To allow Choreo to connect to your GitHub account, click **Authorize with GitHub**. If you have not already connected your GitHub repository to Choreo, enter your GitHub credentials and select the repository you created in the prerequisites section to install the [Choreo GitHub App](https://github.com/marketplace/choreo-apps). - - Alternatively, you can paste the [Choreo samples repository](https://github.com/wso2/choreo-samples) URL in the **Provide Repository URL** field to connect to it without requiring authorization from the [Choreo Apps](https://github.com/marketplace/choreo-apps) GitHub application. However, authorizing the repository with the [Choreo GitHub App](https://github.com/marketplace/choreo-apps) is necessary if you want to enable [**Auto Deploy**](https://wso2.com/choreo/docs/choreo-concepts/ci-cd/#deploy) for the component. + Alternatively, select the **Use Public GitHub Repository** option and paste the [Choreo samples repository](https://github.com/wso2/choreo-samples) URL in the **Provide Repository URL** field to connect to it without requiring authorization from the [Choreo Apps](https://github.com/marketplace/choreo-apps) GitHub application. However, authorizing the repository with the [Choreo GitHub App](https://github.com/marketplace/choreo-apps) is necessary if you want to enable [**Auto Deploy**](https://wso2.com/choreo/docs/choreo-concepts/ci-cd/#deploy) for the component. !!! note The **Choreo GitHub App** requires the following permissions: @@ -70,22 +58,29 @@ To create a NodeJS service component, follow these steps: You can [revoke access](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/reviewing-your-authorized-integrations#reviewing-your-authorized-github-apps) if you do not want Choreo to have access to your GitHub account. However, write access is exclusively utilized for sending pull requests to a user repository. Choreo will not directly push any changes to a repository. -7. Under **Connect Your Repository**, enter the following information: +5. Under **Connect a Git Repository**, enter the following information: | **Field** | **Value** | |-------------------------|-------------------------| | **Organization** | Your GitHub account | | **GitHub Repository** | **`choreo-samples`** | | **Branch** | **`main`** | + | **Component Directory** | `websocket-chat-app/websocket-chat-service-nodejs` | -8. Select **NodeJS** as the buildpack. -9. Enter the following information: +6. Select **NodeJS** as the buildpack and **18.x.x** as the Language Version - | **Field** | **Value** | - |--------------------------------|-----------------------------------------------------| - | **NodeJS Project Directory** | `websocket-chat-app/websocket-chat-service-nodejs` | +8. Enter a display name, a unique name, and a description for the service component. You can enter the values given below: + + !!! info + In the **Component Name** field, you must specify a name to uniquely identify the component in various contexts. The value is editable only at the time you create the component. You cannot change the name after you create the component. + + | **Field** | **Value** | + |---------------------------|-------------------------| + | **Component Display Name**| `NodeJS Chat Service` | + | **Component Name** | `nodejs-chat-service` | + | **Description** | Manage a chat service | -10. Click **Create**. This creates the component and takes you to the **Overview** page of the component. +9. Click **Create**. This creates the component and takes you to the **Overview** page of the component. You have successfully created a service component that provides a WebSocket API built with NodeJS. The next step is to proceed with building and deploying the service. diff --git a/en/docs/develop-components/develop-services/service-component-overview.md b/en/developer-docs/docs/develop-components/develop-services/service-component-overview.md similarity index 100% rename from en/docs/develop-components/develop-services/service-component-overview.md rename to en/developer-docs/docs/develop-components/develop-services/service-component-overview.md diff --git a/en/developer-docs/docs/develop-components/develop-web-applications/build-and-deploy-a-single-page-web-application.md b/en/developer-docs/docs/develop-components/develop-web-applications/build-and-deploy-a-single-page-web-application.md new file mode 100644 index 000000000..0f88fffd0 --- /dev/null +++ b/en/developer-docs/docs/develop-components/develop-web-applications/build-and-deploy-a-single-page-web-application.md @@ -0,0 +1,197 @@ +# Build and Deploy a Single-Page Web Application + +A web application is an application program hosted on a server and serves ingress traffic through a browser. In Choreo, you can deploy a web application by creating a Web Application component and connecting it to a Git repository that contains the implementation of the web application. Web applications can fall into one of the following categories: + +- **Single page applications (SPAs)**: Examples include React, Angular, Vue, Svelte, etc. +- **Web servers**: These serve static content or provide server-side rendering/static site generation (SSR/SSG). +- **Static content**: Examples include websites and other static resources that do not require a backend, usually comprising static HTML/JS/CSS files. + +## Prerequisites + +- To deploy a web application component, you must have a GitHub account with a repository containing the web application's implementation. For this guide, fork the [Choreo samples repository](https://github.com/wso2/choreo-samples), which contains the sample web application implementation. + +## Create a web application + +You can create a web application in Choreo as follows: + +### Build and deploy a SPA from source code + +1. To create a web application component, connect a repository that includes the web application source code. +2. Select the relevant buildpack: Default buildpacks include **React**, **Angular**, and **Vue.js**. If you are using a different SPA framework, you can try one of these buildpacks because the configurations can be overridden to support most JavaScript-based SPAs. +3. Enter the build command: Based on your package manager (NPM, yarn, or pnpm). The relevant package manager is run based on the dependency lock file in your repository (defaults to NPM if no lock file is present). +4. Specify the build output directory. +5. Specify the NodeJS version: Choreo does not pick the Node.js version from the `package.json` engine property. The required Node version must be explicitly set in the build configuration. + +Once you create the Web Application component, Choreo automatically generates a build pipeline for your single-page application and deploys it. + +### Bring your Dockerfile + +1. To create a web application component, connect a repository that contains the Dockerfile for your containerized web application. +2. Commit a Dockerfile to your connected Git repository to have full control over your build process. + +This approach is recommended if you are deploying a web server and not just a single-page application (or a single-page application with a complex build process). + +### Host static websites + +1. Create a web application component and connect it to the GitHub repository that contains the required static assets. +2. Select the **Static Websites** buildpack: This buildpack does not trigger a build process. It only fetches the files from the path specified in the repository and serves them as-is. + +## Build and deploy a SPA from source code + +Follow the steps below to create a sample Web Application component and deploy it in Choreo: + +1. Sign in to the Choreo Console at [https://console.choreo.dev/login/](https://console.choreo.dev/login/). This opens the **Project Home** page. +2. If you already have one or more components in your project, click **+ Create**. Otherwise, proceed to the next step. +3. Click the **Web Application** card. +6. Click **Authorize with GitHub** to connect Choreo to your GitHub account. If you haven't connected your GitHub repository to Choreo, enter your credentials and select the repository you forked earlier to install the [Choreo GitHub App](https://github.com/marketplace/choreo-apps). + + Alternatively, select the **Use Public GitHub Repository** option and paste the [Choreo samples repository](https://github.com/wso2/choreo-samples) URL in the **Provide Repository URL** field. However, enabling [**Auto Deploy**](https://wso2.com/choreo/docs/choreo-concepts/ci-cd/#deploy) requires authorizing the repository with the [Choreo GitHub App](https://github.com/marketplace/choreo-apps). + + !!! note + The **Choreo GitHub App** requires: + - Read and write access to code and pull requests. + - Read access to issues and metadata. + + You can [revoke access](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/reviewing-your-authorized-integrations#reviewing-your-authorized-github-apps) at any time. Write access is only used for sending pull requests; Choreo will not push changes directly to your repository. + +7. Enter the following information: + + | **Field** | **Description** | + |---------------------------|------------------------| + | **GitHub Account** | Your account | + | **GitHub Repository** | choreo-samples | + | **Branch** | main | + | **Component Directory** | /react-single-page-app | + +8. Select **React** as the **Buildpack**. +9. Enter the following information: + + | **Field** | **Description** | + |---------------------------|------------------------| + | **Build Command** | `npm run build` | + | **Build Path** | `build` | + | **Node Version** | `18` | + + !!! tip + Managed authentication is enabled by default when you create a web application using **React**, **Angular**, or **Vue.js** buildpacks. To learn how to set up authentication for your web application with Choreo's managed authentication, see [Secure Web Applications with Managed Authentication](../../authentication-and-authorization/secure-web-applications-with-managed-authentication.md). + +4. Specify a display name, a unique name and description for the component. +10. Click **Create**. Choreo initializes the component with the sample implementation and opens the **Overview** page of the component. + +You have successfully created a Web Application component from the source code. Now let's build and deploy the web application. + +## Build your web application + +1. In the left navigation menu, click **Build**. +2. In the **Builds** pane, click **Build**. This opens the **Commits** pane, where you can see all the commits related to the component. +3. Select the latest commit and click **Build**. This triggers the build process and displays the progress in the **Build Logs** pane. + + You can access the following scans in the **Build Logs** pane: + + - **Dockerfile Scan**: Choreo checks if a non-root user ID is assigned to the Docker container to ensure security. If no non-root user is specified, the build will fail. + - **Container (Trivy) Vulnerability Scan**: Detects vulnerabilities in the final Docker image. If critical vulnerabilities are detected, the build will fail. + + !!! info + If you have Choreo environments on a private data plane, you can ignore these vulnerabilities and proceed with the deployment. + + !!! note + The build process may take some time. Once complete, the build status will be listed in the **Builds** pane. Here, you will see the build status as **Success**. + +## Deploy and access your web application + +1. In the left navigation menu, click **Deploy**. +2. In the **Set Up** card, click **Configure and Deploy**. This opens the **Configure & Deploy** pane. In this guide, you do not need to add a file mount. +3. Click **Next** to proceed to the **Authentication Settings** pane. +4. Keep the default settings and click **Deploy**. + + !!! note + The deployment process may take a few minutes. Once complete, the **Deployment Status** will show as **Active** in the **Development** card. + +5. To verify that the web application is hosted successfully, click the **Web App URL** in the **Development** card. This takes you to the web application. + +## Create a short URL for your web application in production + +!!! info + This feature is only available on the Choreo cloud data plane. + +When you promote your component to the Production environment, you can create a personalized short URL for your web application. The URL follows the `https://{your-short-prefix}.choreoapps.dev` structure, where you can select a name of your preference for `{your-short-prefix}`. + +1. Click **Promote** in the **Development** card and promote your web application to production. +2. In the **Production** card, click **Create a short URL**. +3. Specify a **Short URL prefix** of your choice and click **Save**. + + !!! note + Short URL names/prefixes are subject to availability, provided on a first-come-first-serve basis. + +## Manage runtime configurations for web applications + +For web applications with a backend server, Choreo allows you to mount runtime configurations and secrets as environment variables and/or file mounts for a specific environment. Alternatively, you can also inject them into the client application during server-side rendering or when serving static content. + +For SPAs that run completely on the browser, Choreo does not support *baking-in* environment variables or other configurations. Instead, Choreo recommends the following approach (applicable to most SPA frameworks, including React): + +!!! note + - With SPAs, anything you mount as a runtime config will be available to your users in the browser. + - **Do not include sensitive secrets that are not browser-safe**. + +1. Go to your forked [Choreo samples repository](https://github.com/wso2/choreo-samples). +2. Open the `public` directory. +3. Create and commit a new file named `config.js` in the `public` directory of your React application. This file should contain the runtime configuration variables you want to expose to your application, such as API endpoints or feature flags. For example: + + ```javascript + window.config = { + apiUrl: 'https://api.example.com', + featureFlags: { + enableNewFeature: true, + enableExperimentalFeature: false, + }, + }; + ``` + +4. In your `index.html` file inside the `public` directory, add a script tag to include the `config.js` file inside the `` tag: + + ```html + + + + + My React App + + +
+ + + + ``` + +5. In your React component, access the configuration variables by referencing the `window.config` object: + + ```javascript + import React from 'react'; + + function MyComponent() { + const apiUrl = window.config.apiUrl; + const enableNewFeature = window.config.featureFlags.enableNewFeature; + const enableExperimentalFeature = window.config.featureFlags.enableExperimentalFeature; + + // ... + } + ``` + +6. When you deploy your component to Choreo, create a config file mount in the specified path for each environment (where your `index.html` expects the `config.js` file). For more details, see [Manage Configurations and Secrets](https://wso2.com/choreo/docs/devops-and-ci-cd/manage-configurations-and-secrets/#apply-a-file-mount-to-your-container). + +## Limitations + +The following limitations are specific to the Choreo cloud data plane: + +- **Request size limit**: 256KB (including headers, cookies, and payloads). +- **Response body size limit**: 20MB. +- **Open ports**: Only one open port is permitted per web application. While you can have multiple ports open for project-level communication within a data plane, incoming traffic from the internet can only be directed to one port. This differs from Service-type components, which support multiple endpoints. + +## Troubleshoot a web application + +- **Blank page or 502 error after deployment**: + If you encounter a blank page or a 502 error after deploying your web application, it typically indicates that the wrong directory is being served. To resolve this issue: + 1. Double-check the build output directory, especially if you are using a Dockerfile-less buildpack. + 2. Ensure that the specified output directory matches the actual output directory generated during the build process. For example, if you have erroneously entered `public/` as the output directory when it should have been `build/`. + +By verifying and correcting the output directory alignment, you should be able to address the issue of encountering a blank page or experiencing a 502 error on deploying your web application. diff --git a/en/developer-docs/docs/develop-components/develop-web-applications/develop-web-applications-locally-with-managed-authentication.md b/en/developer-docs/docs/develop-components/develop-web-applications/develop-web-applications-locally-with-managed-authentication.md new file mode 100644 index 000000000..d3954e82b --- /dev/null +++ b/en/developer-docs/docs/develop-components/develop-web-applications/develop-web-applications-locally-with-managed-authentication.md @@ -0,0 +1,77 @@ +# Develop Web Applications Locally with Choreo’s Managed Authentication + +Choreo’s managed authentication capability provides a set of backend for frontend (BFF) endpoints to facilitate authentication and authorization for web applications. These endpoints are readily available for single-page web applications deployed on Choreo. + +As a web application developer, you may need to run the application on your local workstation. Choreo’s local development capability ensures that authentication and authorization during local development work the same way as they do when the application is deployed to Choreo, eliminating the need for code changes. + +This guide explains how to configure and use Choreo’s local development capability to streamline your workflow. + +## How local development works in Choreo + +Local development uses a proxy that sits in front of the locally running web application. This proxy intercepts all incoming requests: +- Requests to `/choreo-apis/*` and `/auth/*` are forwarded to Choreo. +- All other requests are forwarded to the locally running web application. + +The proxy runs on HTTPS using a self-signed certificate, which is essential for secure, HTTP-only cookie-based managed authentication. Once the proxy is running, you can access the web application using the proxy's URL and start developing locally. The behavior of the web application, in terms of managed authentication, will mirror its behavior when deployed to Choreo. + +## Configure local development + +### Prerequisites + +- Create a single-page application (SPA) with managed authentication enabled. For details, see [Secure Web Applications with Managed Authentication](../../authentication-and-authorization/secure-web-applications-with-managed-authentication.md#step-1-set-up-managed-authentication-for-your-web-application). +- Promote and deploy the application to the environment where you want to enable local development. + + !!! note + - The locally running web application will use the same managed authentication configuration as the environment where local development is configured. + - Local development is only allowed in non-critical environments. + +### Apply configurations + +1. Sign in to the Choreo Console. +2. In the **Component Listing** pane, click on the component you created and deployed. +3. In the left navigation menu, click **Deploy**. +4. Go to the respective environment card and click **Local Development**. +5. In the **Local Development** pane, toggle **Local Development** to enable it. +6. (Optional) To update the port on which the local development proxy server runs, expand **Advanced Configurations** and specify a value for **Proxy Port**. +7. Click **Apply**. + +You have now configured local development. The next section explains how to access your web application for local development. + +## Access your web application locally + +### Prerequisites + +- Ensure local development is enabled in the desired environment. +- Ensure your web application is running locally on `http://localhost` on a specific port. + +### Access your web application locally + +You can use either the Choreo built-in identity provider or an external identity provider to access your web application locally. + +=== "Use the Choreo built-in identity provider" + + 1. Sign in to the Choreo Console. + 2. In the **Component Listing** pane, click on the component you created and deployed. + 3. In the left navigation menu, click **Deploy**. + 4. Go to the respective environment card and click **Local Development**. + 5. In the **Local Development** pane, copy the command under **Step 1**. + 6. Paste the command in a terminal, replace `[APP_PORT]` with the port on which your application is running locally, and run the command. + 7. To access the application, go to the URL provided under **Step 2** in the **Local Development** pane. + + !!! note + The local development proxy runs on HTTPS using a self-signed certificate. Your browser may warn that the certificate is not valid. Accept the risk and proceed. + +=== "Use an external identity provider" + + 1. Sign in to the Choreo Console. + 2. In the **Component Listing** pane, click on the component you created and deployed. + 3. In the left navigation menu, click **Deploy**. + 4. Go to the respective environment card and click **Local Development**. + 5. In the **Local Development** pane, copy the redirect URLs under **Step 1**. + 6. Go to the settings in the OAuth application in your identity provider and specify the copied URLs as allowed redirect URLs. + 7. In the **Local Development** pane, copy the command under **Step 2**. + 8. Paste the command in a terminal, replace `[APP_PORT]` with the port on which your application is running locally, and run the command. + 9. To access the application, go to the URL provided under **Step 3** in the **Local Development** pane. + + !!! note + The local development proxy runs on HTTPS using a self-signed certificate. Your browser may warn that the certificate is not valid. Accept the risk and proceed. diff --git a/en/developer-docs/docs/develop-components/integrate-unit-tests-into-the-build-pipeline.md b/en/developer-docs/docs/develop-components/integrate-unit-tests-into-the-build-pipeline.md new file mode 100644 index 000000000..ae73d8439 --- /dev/null +++ b/en/developer-docs/docs/develop-components/integrate-unit-tests-into-the-build-pipeline.md @@ -0,0 +1,35 @@ +# Integrate Unit Tests into the Build Pipeline + +Choreo allows you to integrate unit tests into the build pipeline, enabling code validation before deployment. This ensures early testing of code changes, reducing the risk of defects in production. + +!!! note + Currently, Choreo supports unit tests only for the `WSO2 MI` buildpack. + +## How it works + +### Step 1: Write tests + +You can create unit tests in your source code using standard testing libraries. For step-by-step instructions on creating unit tests for WSO2 Micro Integrator projects, see [Creating a Unit Test Suite](https://mi.docs.wso2.com/en/latest/develop/creating-unit-test-suite/). + +### Step 2: Enable unit tests + +1. Sign in to the [Choreo Console](https://console.choreo.dev/). +2. In the **Component Listing** pane, click the component for which you want to enable unit tests. +3. In the left navigation menu, click **Build**. +4. On the **Build** page, click to edit **Build Configurations**. +5. Turn on the **Unit Test** toggle. +6. Click **Save**. + +### Step 3: Trigger a new build + +- On the **Build** page, click **Build Latest**. + +This starts a new build with unit tests enabled. You can monitor its progress in the **Build Details** pane. + +## View failed unit tests + +If a unit test fails during the build, you can view its detailed logs for troubleshooting. Click **View Details** corresponding to the failed build, then expand the failed unit test step to view the logs. + +## Explore a sample + +To see unit tests in action within the build pipeline, try out the [WSO2 MI helloworld](https://github.com/wso2/choreo-samples/tree/main/hello-world-mi) sample. diff --git a/en/docs/develop-components/manage-component-source-configurations.md b/en/developer-docs/docs/develop-components/manage-component-source-configurations.md similarity index 69% rename from en/docs/develop-components/manage-component-source-configurations.md rename to en/developer-docs/docs/develop-components/manage-component-source-configurations.md index 2b64aa23e..e5acb74eb 100644 --- a/en/docs/develop-components/manage-component-source-configurations.md +++ b/en/developer-docs/docs/develop-components/manage-component-source-configurations.md @@ -6,8 +6,7 @@ The source configuration file must be committed to your repository within the `. !!! note - The `component-config.yaml` and `endpoints.yaml` files will eventually be deprecated and replaced by the `component.yaml` file. - - For details on how you can migrate to the `component.yaml` file from the `component-config.yaml` file, see [Migrate from the `component-config.yaml`](#migrate-from-the-component-configyaml-file). - - For details on how you can migrate to the `component.yaml` file from the `endpoints.yaml` file, see [Migrate from the `endpoints.yaml`](#migrate-from-the-endpointsyaml-file). + - For details on how to seamlessly update to the latest `component.yaml` file`, see [Update to the latest source configuration file](#update-to-the-latest-source-configuration-file). - Choreo prioritizes configuration files in the following order: `component.yaml` takes the highest precedence, followed by `component-config.yaml`, and then `endpoints.yaml`. ## Overview of the `component.yaml` file @@ -68,7 +67,21 @@ Click the respective tab to view the structure for your current configuration fi - name: hr-connection # +required service identifer of the dependent component. resourceRef: service:/HRProject/UserComponent/v1/ad088/PUBLIC - + # +optional Defines runtime configurations + configurations: + # +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. @@ -80,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. | + | **configurations** | 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. @@ -92,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: @@ -115,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 `configurations` 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 `configurations` 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 @@ -147,20 +178,20 @@ 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 service references from the Internal Marketplace. - serviceReferences: - # +required Name of the service reference. - - name: choreo:///apifirst/HRProject/UserComponent/ad088/v1/PUBLIC - # +required Name of the connection instance. - connectionConfig: 19d2648b-d29c-4452-afdd-1b9311e81412 - # +required Environment variables injected into the component for connection configuration. - env: - # +required Key name of the connection configuration. - - from: ServiceURL - # +required Environment variable injected into the container. - to: SERVICE_URL + # +optional Outgoing connection details for the component. + dependencies: + # +optional Defines the service references from the Internal Marketplace. + serviceReferences: + # +required Name of the service reference. + - name: choreo:///apifirst/HRProject/UserComponent/ad088/v1/PUBLIC + # +required Name of the connection instance. + connectionConfig: 19d2648b-d29c-4452-afdd-1b9311e81412 + # +required Environment variables injected into the component for connection configuration. + env: + # +required Key name of the connection configuration. + - from: ServiceURL + # +required Environment variable injected into the container. + to: SERVICE_URL ``` 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. @@ -179,20 +210,20 @@ 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. |

Dependency configurations

- 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: @@ -200,9 +231,9 @@ Click the respective tab to view the structure for your current configuration fi |----------------------|--------------|----------------------------------------------------------------------------------| | **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. | - |       **.from** | Required | The key name of the connection configuration. | - |       **.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. @@ -326,38 +357,54 @@ 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.| -## Migration guide +## Update to the latest source configuration file + +With the upcoming deprecation of the `component-config.yaml` file and the `endpoints.yaml` file, Choreo provides a seamless process to move to the latest `component.yaml` version of the `component.yaml` file. Follow these steps to transition seamlessly: + +### Step 1: Identify whether your current source configuration file is outdated + +You can determine whether you’re using an outdated configuration file in the following ways: + +- **During a build:** + - On the **Build** page, after triggering a build, a warning will appear if your source configuration file is outdated. Click **View Details** in the **Initialization** -> **Source Config Validation** step. You will see an information banner with an option to update the file. + +- **In existing deployments:** + - If an existing deployment uses a build with an outdated source configuration file, you will see a warning icon on the build card of the relevant environment card. + + +### Step 2: Generate the latest `component.yaml` file + +- In either of the scenarios above, click **Update** to initiate the process of generating the latest `component.yaml` file. The updated file will retain your existing configurations to ensure a smooth update process. + + +### Step 3: Add the generated configuration file to your repository + +1. Download the generated `component.yaml` file. +2. Replace the existing source configuration file in the `.choreo` folder within your source repository. + - Ensure the file name is `component.yaml`. -With the upcoming deprecation of the `component-config.yaml` file and the `endpoints.yaml` file, Choreo provides a seamless migration path to the `component.yaml` file. See the following guidelines for details depending on the configuration you want to migrate from: -### Migrate from the `component-config.yaml` file +### Step 4: Trigger a new build -To migrate from the `component-config.yaml` file to the `component.yaml` file, do the following: +1. Commit the new `component.yaml` file to your repository. Push changes to the remote Git repository. +2. Trigger a build using the latest commit. -- Add the `schemaVersion` in the `component.yaml` and omit `apiVersion` and `kind`. -- Move endpoint configurations from the `spec.inbound` section to the `endpoints` section in the `component.yaml` file. - - Copy the value of `spec.inbound.context` to `endpoints.service.basePath`. - - Copy the value of `spec.inbound.port` to `endpoints.service.port`. - - Copy the value of `spec.inbound.networkVisibility` to `endpoints.networkVisibilities`. -- Move dependency configurations from the `spec.outbound` section to the `dependencies` section in the `component.yaml` file. +### Step 5: Verify the update -### Migrate from the `endpoints.yaml` file +Once the build is complete: -To migrate from the `endpoints.yaml` file to the `component.yaml` file, do the following: + - Deploy the build. + - Confirm that the warning messages no longer appear. -- Add the `schemaVersion` in the `component.yaml` and omit `version`. -- Move endpoint configurations from the `endpoints.yaml` file to the `endpoints` section in the `component.yaml` file. - - Copy the value of `context` to `endpoints.service.basePath`. - - Copy the value of `port` to `endpoints.service.port`. - - Copy the value of `networkVisibility` to `endpoints.networkVisibilities`. +You can benefit from the latest features and enhancements provided by the updated source configuration file. diff --git a/en/docs/develop-components/manage-deployment-tracks-for-choreo-components.md b/en/developer-docs/docs/develop-components/manage-deployment-tracks-for-choreo-components.md similarity index 100% rename from en/docs/develop-components/manage-deployment-tracks-for-choreo-components.md rename to en/developer-docs/docs/develop-components/manage-deployment-tracks-for-choreo-components.md diff --git a/en/docs/develop-components/manage-the-micro-integrator-runtime-version-in-your-integration-project.md b/en/developer-docs/docs/develop-components/manage-the-micro-integrator-runtime-version-in-your-integration-project.md similarity index 100% rename from en/docs/develop-components/manage-the-micro-integrator-runtime-version-in-your-integration-project.md rename to en/developer-docs/docs/develop-components/manage-the-micro-integrator-runtime-version-in-your-integration-project.md diff --git a/en/docs/develop-components/sharing-and-reusing/create-a-connection.md b/en/developer-docs/docs/develop-components/sharing-and-reusing/create-a-connection.md similarity index 91% rename from en/docs/develop-components/sharing-and-reusing/create-a-connection.md rename to en/developer-docs/docs/develop-components/sharing-and-reusing/create-a-connection.md index c019e123e..22c11e694 100644 --- a/en/docs/develop-components/sharing-and-reusing/create-a-connection.md +++ b/en/developer-docs/docs/develop-components/sharing-and-reusing/create-a-connection.md @@ -27,6 +27,9 @@ To create a connection to a service or a database, follow the step-by-step instr This creates the connection and displays its details for each environment, along with an inline guide on how to use the connection in your component. + !!! note + During connection creation, secret values for the lowest environment are visible, allowing you to copy them for local use if necessary. Secret values for higher environments remain hidden to ensure security +

Create a connection to an external service

Follow these steps to create a connection to an external service: @@ -69,5 +72,8 @@ To create a connection to a service or a database, follow the step-by-step instr 3. Click **Create**. This creates the connection and displays the database connection details for each environment, along with an inline guide on how to use the connection in your component. + + !!! note + During connection creation, secret values for the lowest environment are visible, allowing you to copy them for local use if necessary. Secret values for higher environments remain hidden to ensure security For step-by-step instructions on using a database in your component, see [Use a Database Connection in Your Component](./use-a-database-connection-in-your-component.md). diff --git a/en/docs/develop-components/sharing-and-reusing/use-a-connection-in-your-service.md b/en/developer-docs/docs/develop-components/sharing-and-reusing/use-a-connection-in-your-service.md similarity index 95% rename from en/docs/develop-components/sharing-and-reusing/use-a-connection-in-your-service.md rename to en/developer-docs/docs/develop-components/sharing-and-reusing/use-a-connection-in-your-service.md index 6558e4bec..b6180b0f0 100644 --- a/en/docs/develop-components/sharing-and-reusing/use-a-connection-in-your-service.md +++ b/en/developer-docs/docs/develop-components/sharing-and-reusing/use-a-connection-in-your-service.md @@ -48,10 +48,20 @@ To integrate another service into your application, click the appropriate tab be | ChoreoAPIKey | CHOREO_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 | |----------------|------------|---------------------------------------|---------------|--------------| @@ -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. diff --git a/en/docs/develop-components/sharing-and-reusing/use-a-connection-in-your-web-application.md b/en/developer-docs/docs/develop-components/sharing-and-reusing/use-a-connection-in-your-web-application.md similarity index 84% rename from en/docs/develop-components/sharing-and-reusing/use-a-connection-in-your-web-application.md rename to en/developer-docs/docs/develop-components/sharing-and-reusing/use-a-connection-in-your-web-application.md index 07bad9ce6..43a084f06 100644 --- a/en/docs/develop-components/sharing-and-reusing/use-a-connection-in-your-web-application.md +++ b/en/developer-docs/docs/develop-components/sharing-and-reusing/use-a-connection-in-your-web-application.md @@ -17,7 +17,7 @@ To connect to a selected service, follow the step-by-step instructions given bel To integrate a service into your application, you must first add the connection configuration as follows: - 1. For single page applications (SPAs), you must add the connection configuration as a file mount. You can mount a file via the **Configurations** pane on the **Deploy** page. You must mount a file (for example, `config.js`) and add the configuration provided in the in-line developer documentation into it. + 1. For single page applications (SPAs), you must add the connection configuration as a file mount. You can mount a file via the **Configurations** pane on the **Deploy** page. You must mount a file (for example, `config.js`) and add the configuration provided in the inline developer documentation into it. The following is a sample configuration: @@ -39,7 +39,7 @@ To connect to a selected service, follow the step-by-step instructions given bel
- + ``` @@ -80,19 +80,34 @@ To connect to a selected service, follow the step-by-step instructions given bel

Step 1: Add the connection configuration

- For single-page applications (SPAs), you must add the connection configuration as a file mount. You can mount a file via the **Configurations** pane on the **Deploy** page. You must mount a file (for example, `config.js`) and add the following configuration into it. + 1. For single-page applications (SPAs), you must add the connection configuration as a file mount. You can mount a file via the **Configurations** pane on the **Deploy** page. You must mount a file (for example, `config.js`) and add the configuration provided in the inline developer documentation into it. + The following is a sample configuration: + + ``` yaml + window.configs = { + apiUrl: '', + consumerKey: '', + consumerSecret: '', + tokenUrl: '', + }; + ``` - The following is a sample configuration: + 2. To ensure accessibility of the `config.js` file via JavaScript at runtime, add a script tag as follows in the `index.html` file to reference the `config.js` file: - ``` yaml - window.configs = { - apiUrl: '', - consumerKey: '', - consumerSecret: '', - tokenUrl: '', - }; - ``` + ``` html + + + + + My React App + + +
+ + + + ``` For other types of web applications, you must add the respective configuration into your application. diff --git a/en/developer-docs/docs/develop-components/sharing-and-reusing/use-a-database-connection-in-your-component.md b/en/developer-docs/docs/develop-components/sharing-and-reusing/use-a-database-connection-in-your-component.md new file mode 100644 index 000000000..51a3edece --- /dev/null +++ b/en/developer-docs/docs/develop-components/sharing-and-reusing/use-a-database-connection-in-your-component.md @@ -0,0 +1,246 @@ +# Use a Database Connection in Your Component + +Choreo allows you to share and reuse Choreo-managed databases, accelerating development and enhancing efficiency in building integrated applications through connections. + +For step-by-step instructions on creating a database connection, see [Create a Connection](create-a-connection.md). + +To learn more about Choreo Connections, see the documentation on [Connections](../../choreo-concepts/connections.md). + +## Consume a database through a connection + +To consume a Choreo-managed database via a connection, follow these steps: + +### Step 1: Add connection configurations + +To integrate a database into your application, click the appropriate tab below based on your current configuration file and follow the step-by-step instructions: + +=== "Component.yaml file (v1.1)" + + 1. Copy and paste the snippet from the developer guide into the `component.yaml` file. + + The following is a sample snippet: + + ``` yaml + + dependencies: + connectionReferences: + - name: + resourceRef: + + ``` + + | Field | Description | + |------------------|---------------------------------------------------------------------| + | name | The name given to the connection. | + | resourceRef | A unique, readable identifier of the database being connected to. | + + + 2. If you've previously added a `connectionReferences` section under `dependencies`, append this as another item under `connectionReferences`. Upon deploying the component, the necessary configurations to establish the connection will be injected into Choreo-defined environment variables. + + The following table details the Choreo-defined environment variables: + + | Configuration Key | Choreo-Defined Environment Variable Name | + |-------------------------|----------------------------------------------------------------| + | HostName | CHOREO__HOSTNAME | + | Port | CHOREO__PORT | + | Username | CHOREO__USERNAME | + | Password | CHOREO__PASSWORD | + | DatabaseName | CHOREO_DATABASENAME | + + + 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. + + + The following table provides details on the configuration keys associated with the connection: + + | Name | Type | Description |Optional | Sensitive | + |----------------|------------|---------------------------------------|---------------|--------------| + | HostName | string | Hostname of the database server | false | false | + | Port | string | Port of the database server | false | false | + | Username | string | Username of the database server | false | false | + | Password | string | Password of the database server | false | true | + | DatabaseName | string | Name of the database | false | false | + ### 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. + + The following is a sample code snippet in NodeJS: + + ``` java + const hostName = process.env.CHOREO__HOSTNAME; + ``` + +=== "Component.yaml file (v1.0)" + + !!! note + The `component.yaml v1.0` file is considered legacy. For new components, we recommend using the latest version, `component.yaml v1.1`, which offers enhanced usability and features. + + 1. Copy and paste the snippet from the developer guide into the `component.yaml` file. + + The following is a sample snippet: + + ``` yaml + + dependencies: + serviceReferences: + - name: database: + connectionConfig: + env: + - from: HostName + to: + - from: Port + to: + - from: Username + to: + - from: Password + to: + - from: DatabaseName + to: + + + ``` + + | Field | Description | + |------------------|-------------------------------------------------------------| + | name | The name of the database you are connecting to. | + | connectionConfig | The unique connection identifier for the connection. | + | env | The environment variable mapping. | + | from | The key of the configuration entry. | + | to | The environment variable name to which Choreo will inject the value of the key.| + + + 2. Replace `` with an appropriate environment variable name of your choice. If you have previously added a service reference section under `dependencies`, append this as another item under `serviceReferences`. + + Upon deploying the component, Choreo automatically populates the specified environment variables with actual values. + + The following table provides details on the configuration keys associated with the connection: + + | Name | Type | Description |Optional | Sensitive | + |----------------|------------|---------------------------------------|---------------|--------------| + | HostName | string | Hostname of the database server | false | false | + | Port | string | Port of the database server | false | false | + | Username | string | Username of the database server | false | false | + | Password | string | Password of the database server | false | true | + | DatabaseName | string | Name of the database | false | false | + +

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. + + The following is a sample code snippet in NodeJS: + + ``` java + const hostName = process.env.HOSTNAME; + ``` + +=== "Component-config.yaml file" + + !!! note + The `component-config.yaml` file is considered legacy. For new components, we recommend using the latest version, `component.yaml v1.1`, which offers enhanced usability and features. + + 1. Copy and paste the snippet from the developer guide into the `component-config` file under the `spec` section. + + The following is a sample snippet: + + ``` yaml + + outbound: + serviceReferences: + - name: database: + connectionConfig: + env: + - from: HostName + to: + - from: Port + to: + - from: Username + to: + - from: Password + to: + - from: DatabaseName + to: + + ``` + + | Field | Description | + |------------------|-------------------------------------------------------------| + | name | The name of the database you are connecting to. | + | connectionConfig | The unique connection identifier for the connection. | + | env | The environment variable mapping. | + | from | The key of the configuration entry. | + | to | The environment variable name to which Choreo will inject the value of the key.| + + + 2. Replace `` with an appropriate environment variable name of your choice. If you have previously added an outbound service reference, append this as another item under `serviceReferences`. + + Upon deploying the component, Choreo automatically populates the specified environment variables with actual values. + + + The following table provides details on the configuration keys associated with the connection: + + | Name | Type | Description |Optional | Sensitive | + |----------------|------------|---------------------------------------|---------------|--------------| + | HostName | string | Hostname of the database server | false | false | + | Port | string | Port of the database server | false | false | + | Username | string | Username of the database server | false | false | + | Password | string | Password of the database server | false | true | + | DatabaseName | string | Name of the database | false | false | + +

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. + + The following is a sample code snippet in NodeJS: + + ``` java + const hostName = process.env.HOSTNAME; + ``` + +### Step 3: Initiate a database connection + +To initiate a connection to the database, follow these steps: + +In this example, you will connect to a MySQL database. + +#### Step 3.1: Install the required packages + +For the MySQL database, install the `mysql2` package using npm: + +```bash +// Install the mysql2 package +npm install mysql2 + +``` + +#### Step 3.2: Import required packages + +```java + +const client = require('mysql2') + +``` + +#### Step 3.3: Establish a connection + +To establish the connection, use the environment variables for `hostName`, `username`, `password`, `databaseName`, and `port` as follows: + +```java + +var connection = client.createConnection({ + host: hostName, + user: username, + password: password, + database: databaseName, + port: port +}); + +connection.connect((err) => { + if (err) { + return; + } + // Connection is successful +}); + +``` + +By following these steps, your component can interact with the Choreo-managed database seamlessly. diff --git a/en/docs/develop-components/submit-and-manage-workflow-approval-requests.md b/en/developer-docs/docs/develop-components/submit-and-manage-workflow-approval-requests.md similarity index 100% rename from en/docs/develop-components/submit-and-manage-workflow-approval-requests.md rename to en/developer-docs/docs/develop-components/submit-and-manage-workflow-approval-requests.md diff --git a/en/docs/develop-components/work-with-the-micro-integrator-runtime-in-choreo.md b/en/developer-docs/docs/develop-components/work-with-the-micro-integrator-runtime-in-choreo.md similarity index 100% rename from en/docs/develop-components/work-with-the-micro-integrator-runtime-in-choreo.md rename to en/developer-docs/docs/develop-components/work-with-the-micro-integrator-runtime-in-choreo.md diff --git a/en/docs/devops-and-ci-cd/autoscale/autoscale-component-replicas.md b/en/developer-docs/docs/devops-and-ci-cd/autoscale/autoscale-component-replicas.md similarity index 100% rename from en/docs/devops-and-ci-cd/autoscale/autoscale-component-replicas.md rename to en/developer-docs/docs/devops-and-ci-cd/autoscale/autoscale-component-replicas.md diff --git a/en/docs/devops-and-ci-cd/autoscale/autoscale-components-with-scale-to-zero.md b/en/developer-docs/docs/devops-and-ci-cd/autoscale/autoscale-components-with-scale-to-zero.md similarity index 100% rename from en/docs/devops-and-ci-cd/autoscale/autoscale-components-with-scale-to-zero.md rename to en/developer-docs/docs/devops-and-ci-cd/autoscale/autoscale-components-with-scale-to-zero.md diff --git a/en/docs/devops-and-ci-cd/configure-container-resources-commands-and-arguments.md b/en/developer-docs/docs/devops-and-ci-cd/configure-container-resources-commands-and-arguments.md similarity index 100% rename from en/docs/devops-and-ci-cd/configure-container-resources-commands-and-arguments.md rename to en/developer-docs/docs/devops-and-ci-cd/configure-container-resources-commands-and-arguments.md diff --git a/en/docs/devops-and-ci-cd/configure-storage.md b/en/developer-docs/docs/devops-and-ci-cd/configure-storage.md similarity index 100% rename from en/docs/devops-and-ci-cd/configure-storage.md rename to en/developer-docs/docs/devops-and-ci-cd/configure-storage.md diff --git a/en/docs/devops-and-ci-cd/configure-vpns-on-the-choreo-cloud-data-plane.md b/en/developer-docs/docs/devops-and-ci-cd/configure-vpns-on-the-choreo-cloud-data-plane.md similarity index 88% rename from en/docs/devops-and-ci-cd/configure-vpns-on-the-choreo-cloud-data-plane.md rename to en/developer-docs/docs/devops-and-ci-cd/configure-vpns-on-the-choreo-cloud-data-plane.md index 18fe9364d..28c66c1bd 100644 --- a/en/docs/devops-and-ci-cd/configure-vpns-on-the-choreo-cloud-data-plane.md +++ b/en/developer-docs/docs/devops-and-ci-cd/configure-vpns-on-the-choreo-cloud-data-plane.md @@ -83,8 +83,11 @@ Follow the steps given below to create a project: #### Step 1.2: Create the Tailscale proxy component -1. On the project home page, click **Service** under **Create a Component**. -2. Enter a display name, component name, and a description for the service. For this guide, let's enter the following values: +1. On the project home page, click **+ Create**, and select the **Service** card to create a service component. +2. Click the **Container Registry** from the **Connect a Docker Image** section +3. In the **Container Registry** list, select **Choreo Samples Registry**. +4. Click the **Tailscale Proxy** card. +5. Enter a display name, component name, and a description for the service. For this guide, let's enter the following values: |Field | Value | |----------------------|--------------------------| @@ -92,9 +95,6 @@ Follow the steps given below to create a project: |Component Name | tailscale-proxy | |Description | Tailscale proxy component| -3. Click the **Container Registry** tab. -4. In the **Container Registry** list, select **Choreo Samples Registry**. -5. Click the **Tailscale Proxy** card. 6. Click **Create**. Now you have successfully created the Tailscale proxy. You can proceed to configure and deploy it. @@ -118,8 +118,19 @@ To configure and deploy the component, follow the steps given below: 1. In the left navigation menu, click **Deploy**. 2. On the **Build Area** card, click **Configure & Deploy**. -3. In the **Environment Configurations** pane that opens, click **+ Add** and add the `TS_AUTH_KEY` environment variable as a secret. To add the environment variable, you must obtain an authentication key from your Tailscale network. - - For details on how to obtain an authentication key from your Tailscale network, see [Auth keys](https://tailscale.com/kb/1085/auth-keys) in the Tailscale documentation. +3. In the **Environment Configurations** pane that opens, click **+ Add** and add the `TS_AUTH_KEY` environment variable as a secret. To add the environment variable, you must obtain an authentication key from your Tailscale network. For details on how to obtain an authentication key from your Tailscale network, see [Auth keys](https://tailscale.com/kb/1085/auth-keys) in the Tailscale documentation. + + !!! info "Note" + The authentication keys obtained from your Tailscale network have an expiration date and require periodic rotation. To avoid manual rotation, you can generate non-expiring authentication keys using OAuth clients. For details, see [Generating long-lived auth keys](https://tailscale.com/kb/1215/oauth-clients#generating-long-lived-auth-keys) in the Tailscale documentation. + + Follow these steps if you want to add an OAuth client secret to the Tailscale proxy component instead of the `TS_AUTH_KEY` environment variable as a secret: + + 1. Define a tag named `choreo-vpn` in your Tailscale ACLs. For details, see [Define a tag](https://tailscale.com/kb/1068/tags#define-a-tag) in the Tailscale documentation. + 2. Create an [OAuth client](https://tailscale.com/kb/1215/oauth-clients) with the following scope, ensuring it is assigned to the `choreo-vpn` tag: + - Keys → Auth Keys → write + 3. Generate the OAuth client and copy the client secret. + 4. Set the client secret as an environment variable named `OAUTH_CLIENT_SECRET`. + 4. Click **Next**. 5. In the **File Mount** pane that opens, click **+ Add**. 6. To mount a configuration file to the Tailscale proxy component and specify the port mapping for the TCP forward proxy running there, do the following: diff --git a/en/developer-docs/docs/devops-and-ci-cd/manage-configuration-groups.md b/en/developer-docs/docs/devops-and-ci-cd/manage-configuration-groups.md new file mode 100644 index 000000000..93f266cc9 --- /dev/null +++ b/en/developer-docs/docs/devops-and-ci-cd/manage-configuration-groups.md @@ -0,0 +1,110 @@ + +# Manage Configuration Groups + +Choreo allows you to create Configuration Groups to efficiently manage reusable configurations across components within your organization. A Configuration Group is a collection of key-value pairs, where values can be defined for multiple environments. This feature ensures consistency and simplifies the management of configurations across environments. + +Configuration groups can be defined at organization level and link to components at deployment time. Once linked, Choreo automatically resolves and mounts the configurations to the respective environments on deployment. You can either link a configuration group to inject the configurations as environment variables or file mounts. + +!!!important + - All configuration group values are encrypted and stored in environment-specific key vaults. + - Management of configuration groups is restricted to users with Choreo Admin, DevOps, and Platform Engineer roles. + - Developers can discover configuration groups available within the organization via the **Choreo Internal Marketplace**. + +## Create a configuration group + +To create a new configuration group, follow the steps given below: + +1. In the [Choreo Console](https://console.choreo.dev/), go to the top navigation menu. Click **Organization** and select your organization. +2. In the left navigation menu, click **DevOps** and then click **Configuration Groups**. +3. On the **Configuration Groups** page, click **Create** and specify the following details to create a new configuration group: + + - **Name**: A name for the configuration group (Unique within the organization). + - **Description**: A description for the configuration group (Optional). + - **Define Keys**: Define the keys for the configuration group. + + - Configuration keys uniquely identify values in a configuration group. You can map these keys to environment variables or file mounts during deployment. Each key must be unique within the group. + + - **Assign Values**: Define values by environment for the keys defined. + + - By default, all the environments are grouped together allowing you to manage configuration smoothly. You can separate and manage configuration values for each environment as needed. + + - **Create**: Click **Create** to create the configuration group. + +4. Now you can link this configuration group to any component within the organization. + +!!!note + - Configuration groups created will be listed in the **Choreo Internal Marketplace**, improving visibility and discoverability for developers. + - All configuration groups will also be listed in the component deployment drawers, allowing developers to easily link them during deployment. + +## Link and use configuration groups + +The configuration groups created at organization level can be linked to any component within the organization. A configuration group can be linked as **Environment Variables** or **File Mounts** at deployment time. + +Linking a configuration group will inject the values defined in the group during deployment. The values are mapped to environment variable names or file names based on the keys defined in the configuration group. If needed, you can customize the environment variable name or file name by updating the mapping at deployment. + +To link a configuration group to a component, follow the steps given below: + +1. Navigate to the component you want to link the configuration group. +2. On the **Deploy** page, click **Configure & Deploy**, this will open the configuration and deployment wizard. +3. In the wizard, link the configuration groups as **Environment Variables** or **File Mounts**, based on your requirements. + + === "Environment Variables" + + - Choose the configuration group you want to link to the component. + - Click **Link** to link the configuration group to the component. + + === "File Mounts" + + - Choose the configuration group you want to link to the component. + - Specify the **Mount Path** to mount the configuration files. + + !!!note + All configurations within the selected configuration group will be mounted as individual files to the specified mount path/directory. + + - Click **Link** to link the configuration group to the component. + +4. Complete the deployment wizard by providing the required details and click **Deploy** to deploy the component with the updated configurations. + +## View & edit a configuration group + +To view & edit a configuration group, follow the steps given below: + +1. In the [Choreo Console](https://console.choreo.dev/), go to the top navigation menu. Click **Organization** and select your organization. +2. In the left navigation menu, click **DevOps** and then click **Configuration Groups**. +3. In the **Configuration Groups** list, select the desired configuration group to view. + + !!!note + - Only non-sensitive configuration values are displayed in the view mode. + - Updating the configuration group will not affect the current deployment; changes will be applied when the component is redeployed. + +### Edit the configuration group + +Configuration keys and values within a configuration group can be modified, and these changes will take effect when the components using the configuration group are redeployed. + +To edit the configuration group definition, click **Edit the Configuration Group** and make the necessary updates: + +- Add or remove configuration keys. +- Update the configuration group's display name and description. + +To edit the configuration values, click the edit icon in the corresponding set of environments and modify the required details: + +- Update configuration values. +- Add a new set of configuration values. +- Add or remove environments from an existing set. + +!!! warning + - **Adding a new environment:** Non-sensitive configuration values will be copied to the new environment, but sensitive values will not be. As a result, sensitive values will be cleared across all environments in the set. **New values must be provided for sensitive configurations.** + - **Removing an environment:** All configuration values for the removed environment will be deleted. + +## Delete a configuration group + +To delete a configuration group, follow the steps given below: + +!!! warning + Deleting a configuration group is a permanent, non-reversible action. Ensure that the configuration group is not linked to any component before deleting it. + +1. In the [Choreo Console](https://console.choreo.dev/), go to the top navigation menu. Click **Organization** and select your organization. +2. In the left navigation menu, click **DevOps** and then click **Configuration Groups**. +3. In the **Configuration Groups** list, click the delete icon next to the configuration group you want to delete. This will display a confirmation dialog with details about the impact of the deletion. +4. Review the details, then type the configuration group name to confirm the deletion. +5. Click **Delete**. diff --git a/en/docs/devops-and-ci-cd/manage-configurations-and-secrets.md b/en/developer-docs/docs/devops-and-ci-cd/manage-configurations-and-secrets.md similarity index 100% rename from en/docs/devops-and-ci-cd/manage-configurations-and-secrets.md rename to en/developer-docs/docs/devops-and-ci-cd/manage-configurations-and-secrets.md diff --git a/en/developer-docs/docs/devops-and-ci-cd/manage-continuous-deployment-pipelines.md b/en/developer-docs/docs/devops-and-ci-cd/manage-continuous-deployment-pipelines.md new file mode 100644 index 000000000..a7675db2c --- /dev/null +++ b/en/developer-docs/docs/devops-and-ci-cd/manage-continuous-deployment-pipelines.md @@ -0,0 +1,111 @@ +# Manage Continuous Deployment Pipelines + +By default, all the organizations in Choreo are provisioned with a default continuous deployment pipeline. + +Environments within an organization are applied to projects in the order specified by the continuous deployment pipeline. The organization's default continuous deployment pipeline is applied to all the projects. You can create additional pipelines and customize the sequence in which environments are applied in projects. + +## Create a new continuous deployment pipeline + +### Prerequisites + +- To create a new continuous deployment pipeline in an organization, you must have the `ENVIRONMENT-MANAGEMENT` permission. By default, `ENVIRONMENT-MANAGEMENT` permission is granted to Admin, Choreo Platform Engineer and Choreo DevOps roles. + +To create a new pipeline, follow the steps given below: + +1. Sign in to [Choreo](https://console.choreo.dev/). +2. In the Choreo Console, go to the top navigation menu and click **Organization**. Then select your organization. +3. In the left navigation menu, click **DevOps** and then click **CD Pipelines**. +4. On the **CD Pipelines** page, click **+ Create Pipeline** and specify the following details required to create a new pipeline: + + - **Name**: A display name for the new pipeline. + - **Mark as Default**: Select if you want to assign this new pipeline as the default pipeline for all new projects. +5. Click **+ Add Environment** and add required environments for the pipeline according to the preferred environment sequence. +6. Click **Create**. + +## Edit a continuous deployment pipeline + +### Prerequisites + +- To edit a continuous deployment pipeline in an organization, you must have the `ENVIRONMENT-MANAGEMENT` permission. By default, `ENVIRONMENT-MANAGEMENT` permission is granted to Admin, Choreo Platform Engineer and Choreo DevOps roles. + +To edit a pipeline, follow the steps given below: + +1. Sign in to [Choreo](https://console.choreo.dev/). +2. In the Choreo Console, go to the top navigation menu and click **Organization**. Then select your organization. +3. In the left navigation menu, click **DevOps** and then click **CD Pipelines**. +4. Click the edit icon corresponding to the pipeline you want to edit. +5. Update the pipeline name, mark the pipeline as default, and change the sequence of environments. +6. Click **Update**. + + +## Delete a continuous deployment pipeline + +To delete a pipeline, follow the steps given below: + +!!! warning + Continuous deployment pipeline deletion is a permanent, non-reversible operation. + +!!! info "Note" + The **default** continuous deployment pipeline of the organization cannot be deleted. + +1. Sign in to [Choreo](https://console.choreo.dev/). +2. In the Choreo Console, go to the top navigation menu and click **Organization**. Then select your organization. +3. In the left navigation menu, click **DevOps** and then click **CD Pipelines**. +4. Click the delete icon corresponding to the pipeline you want to delete. This displays a confirmation dialog with details on the impact of deletion. + + !!! info "Note" + If the pipeline is utilized by one or more projects, deletion will not be permitted. To proceed with deleting such a pipeline, you must first remove it from every project that is currently using it. + +5. Review the details, then type the pipeline name to confirm the deletion. +6. Click **Delete**. + + +## Add a continuous deployment pipeline to a project + +### Prerequisites + +- To add a continuous deployment pipeline to a project, you must have the `ENVIRONMENT-MANAGEMENT` or `PROJECT-MANAGEMENT` permission. By default, `ENVIRONMENT-MANAGEMENT` permission is granted to Admin, Choreo Platform Engineer and Choreo DevOps roles and `PROJECT-MANAGEMENT` permission is granted to Admin, Choreo DevOps, and Project Admin roles. + +To add a pipeline to a project, follow the steps given below: + +1. Sign in to [Choreo](https://console.choreo.dev/). +2. In the Choreo Console, go to the top navigation menu and click **Organization**. Then select your organization. +3. Click the project you want to add the pipeline. +4. In the left navigation menu, click **DevOps** and then click **CD Pipelines**. +5. Click **+ Add** and select the pipelines you want to add to the project. +6. Click **Add**. + + +## Remove a continuous deployment pipeline from a project + +### Prerequisites + +- To remove a continuous deployment pipeline from a project, you must have the `ENVIRONMENT-MANAGEMENT` or `PROJECT-MANAGEMENT` permission. By default, `ENVIRONMENT-MANAGEMENT` permission is granted to Admin, Choreo Platform Engineer and Choreo DevOps roles and `PROJECT-MANAGEMENT` permission is granted to Admin, Choreo DevOps, and Project Admin roles. + +To remove a pipeline from a project, follow the steps given below: + +1. Sign in to [Choreo](https://console.choreo.dev/). +2. In the Choreo Console, go to the top navigation menu and click **Organization**. Then select your organization. +3. Click the project you want to remove the pipeline. +4. In the left navigation menu, click **DevOps** and then click **CD Pipelines**. +5. Click **Remove** corresponding to the pipeline you want to remove from the project. This displays a confirmation dialog with details on the impact of deletion. +6. Review the details, then type the pipeline name to confirm the deletion. +7. Click **Remove**. + +## Change default continuous deployment pipeline of a project + +### Prerequisites + +- To change the default continuous deployment pipeline of a project, you must have the `ENVIRONMENT-MANAGEMENT` or `PROJECT-MANAGEMENT` permission. By default, `ENVIRONMENT-MANAGEMENT` permission is granted to Admin, Choreo Platform Engineer and Choreo DevOps roles and `PROJECT-MANAGEMENT` permission is granted to Admin, Choreo DevOps, and Project Admin roles. + +To change the default pipeline of a project, follow the steps given below: + +1. Sign in to [Choreo](https://console.choreo.dev/). +2. In the Choreo Console, go to the top navigation menu and click **Organization**. Then select your organization. +3. Click the project you want to change the default pipeline. +4. In the left navigation menu, click **DevOps** and then click **CD Pipelines**. +5. Click **Set as Default** corresponding to the pipeline you want to set as the default pipeline for the project. This displays a confirmation dialog that details the impact of setting the new pipeline as the project default. +6. Click **Confirm**. + + !!! info "Note" + The **default** continuous deployment pipeline is configured separately at both the organization and project levels. When a project is created, it inherits the organization's **default** pipeline. The project's **default** pipeline then defines the default promotion order for its components on the Deploy page. diff --git a/en/developer-docs/docs/devops-and-ci-cd/manage-environments.md b/en/developer-docs/docs/devops-and-ci-cd/manage-environments.md new file mode 100644 index 000000000..811ea95a9 --- /dev/null +++ b/en/developer-docs/docs/devops-and-ci-cd/manage-environments.md @@ -0,0 +1,44 @@ +# Manage Environments + +By default, all projects created in the cloud data planes (irrespective of the data plane region) are provisioned with two environments (i.e., development and production). + +The environments are listed in the order of deployment and promotion. The initial deployment takes place in the first environment and you can proceed to promote a component to subsequent environments. + +## Create a new environment + +### Prerequisites + +- To create a new environment in a private data plane organization, you must have the `ENVIRONMENT-MANAGEMENT` permission. By default, `ENVIRONMENT-MANAGEMENT` permission is granted to Admin, Choreo Platform Engineer and Choreo DevOps roles. + +To create a new environment, follow the steps given below: + +1. Sign in to [Choreo](https://console.choreo.dev/). +2. In the Choreo Console, go to the top navigation menu and click **Organization**. Then select your organization. +3. In the left navigation menu, click **DevOps** and then click **Environments**. +4. On the **Environments** page, click **Create** and specify the following details to create a new environment: + + - **Name**: A display name for the new environment. + - **Data Plane** - The data plane to create the new environment. + + !!!tip + The **Data Plane** list displays all the private data planes registered under your organization. + + - **DNS Prefix**: A DNS prefix to identify the exposed APIs in the environment. Here, the base domain depends on the custom domain attached to the API gateways provisioned on the selected data plane. + - **Mark environment as a Production environment**: Select if you want this environment to be a production environment. + + !!!tip + In Choreo, you can have multiple non-production and production environments. To work in a production environment, you must have privileged permissions to access and deploy to production environments. + +## Delete an environment + +To delete an environment, follow the steps given below: + +!!! warning + Environment deletion is a permanent, non-reversible operation. + +1. Sign in to [Choreo](https://console.choreo.dev/). +2. In the Choreo Console, go to the top navigation menu and click **Organization**. Then select your organization. +3. In the left navigation menu, click **DevOps** and then click **Environments**. +4. In the **Environments** list, click the delete icon corresponding to the environment you want to delete. This displays a confirmation dialog with details on the impact of deletion. +5. Review the details, then type the environment name to confirm the deletion. +6. Click **Delete**. diff --git a/en/docs/devops-and-ci-cd/set-up-health-checks.md b/en/developer-docs/docs/devops-and-ci-cd/set-up-health-checks.md similarity index 100% rename from en/docs/devops-and-ci-cd/set-up-health-checks.md rename to en/developer-docs/docs/devops-and-ci-cd/set-up-health-checks.md diff --git a/en/docs/devops-and-ci-cd/view-runtime-details.md b/en/developer-docs/docs/devops-and-ci-cd/view-runtime-details.md similarity index 100% rename from en/docs/devops-and-ci-cd/view-runtime-details.md rename to en/developer-docs/docs/devops-and-ci-cd/view-runtime-details.md diff --git a/en/docs/index.md b/en/developer-docs/docs/index.md similarity index 100% rename from en/docs/index.md rename to en/developer-docs/docs/index.md diff --git a/en/docs/integrate-and-manage-external-services/integrate-and-manage-gen-ai-services.md b/en/developer-docs/docs/integrate-and-manage-external-services/integrate-and-manage-gen-ai-services.md similarity index 100% rename from en/docs/integrate-and-manage-external-services/integrate-and-manage-gen-ai-services.md rename to en/developer-docs/docs/integrate-and-manage-external-services/integrate-and-manage-gen-ai-services.md diff --git a/en/docs/integrate-and-manage-external-services/integrate-and-manage-third-party-services.md b/en/developer-docs/docs/integrate-and-manage-external-services/integrate-and-manage-third-party-services.md similarity index 100% rename from en/docs/integrate-and-manage-external-services/integrate-and-manage-third-party-services.md rename to en/developer-docs/docs/integrate-and-manage-external-services/integrate-and-manage-third-party-services.md diff --git a/en/docs/manage-databases-and-caches/add-choreo-managed-databases-and-caches-to-the-marketplace.md b/en/developer-docs/docs/manage-databases-and-caches/add-choreo-managed-databases-and-caches-to-the-marketplace.md similarity index 62% rename from en/docs/manage-databases-and-caches/add-choreo-managed-databases-and-caches-to-the-marketplace.md rename to en/developer-docs/docs/manage-databases-and-caches/add-choreo-managed-databases-and-caches-to-the-marketplace.md index c043e8944..a667ead84 100644 --- a/en/docs/manage-databases-and-caches/add-choreo-managed-databases-and-caches-to-the-marketplace.md +++ b/en/developer-docs/docs/manage-databases-and-caches/add-choreo-managed-databases-and-caches-to-the-marketplace.md @@ -3,39 +3,39 @@ When you create a Choreo-managed database or cache, you can add it to the Marketplace, making it available for consumption through a connection. !!! note - To add a Choreo-managed database or cache to the Marketplace, you must register at least one credential for it. + To add a Choreo-managed database or cache to the Marketplace, you must import at least one credential for it. -## Step 1: Register credentials +## Step 1: Import credentials -To register credentials, you can either use the default super admin credentials or the credentials you create using the super admin credentials. When you create a database or cache server, super admin credentials are generated by default. You can use these super admin credentials to create new user credentials. The steps to create new user credentials depend on the type of database or cache you are using. +To import credentials, you can either use the default super admin credentials or the credentials you create using the super admin credentials. When you create a database or cache server, super admin credentials are generated by default. You can use these super admin credentials to create new user credentials. The steps to create new user credentials depend on the type of database or cache you are using. -You can use the registered credentials to create a connection. During connection setup, you must select credentials for each database from the list of available credentials. +You can use the imported credentials to create a connection. During connection setup, you must select credentials for each database from the list of available credentials. -To register credentials for a database, follow these steps: +To import credentials for a database, follow these steps: 1. Sign in to the [Choreo Console](https://console.choreo.dev/). 2. Go to the Choreo Console header and select your organization from the **Organization** list. 3. In the left navigation menu, click **Dependencies** and then click **Databases**. 4. Click on a required database to view its details. 5. Click the **Databases** tab. -6. Click to expand the database for which you want to register credentials, then click **Add Credentials**. -7. In the **Add Credentials** dialog, do one of the following depending on your requirements: +6. Click to expand the database for which you want to import credentials, then click **Import Credentials**. +7. In the **Import Credentials** dialog, do one of the following depending on your requirements: - - Select **Add New Credentials** and specify the following: + - Select **Use Created Credentials** and specify the following: - A display name for the credentials. - The database credentials you created to use when setting up database connections in Choreo. - The environment where you want to use the credentials. The steps to create new user credentials depend on the type of database or cache you are using. In general, you must log in to your database server as the super admin using a command-line interface or a database management tool. Then, create new database users with the required permission levels. - - Select **Add Super Admin Credentials** and specify the following: + - Select **Use Super Admin Credentials** and specify the following: - A display name for the credentials. - The environment where you want to use the credentials. 8. Click **Save**. !!! tip - Choreo allows you to delete registered credentials to prevent their use when establishing new connections. However, deleting credentials will not affect any existing database connections that are already using them. + Choreo allows you to delete imported credentials to prevent their use when establishing new connections. However, deleting credentials will not affect any existing database connections that are already using them. ## Step 2: Add the database or cache to the Marketplace diff --git a/en/docs/manage-databases-and-caches/choreo-managed-caches.md b/en/developer-docs/docs/manage-databases-and-caches/choreo-managed-caches.md similarity index 100% rename from en/docs/manage-databases-and-caches/choreo-managed-caches.md rename to en/developer-docs/docs/manage-databases-and-caches/choreo-managed-caches.md diff --git a/en/docs/manage-databases-and-caches/choreo-managed-databases-and-caches.md b/en/developer-docs/docs/manage-databases-and-caches/choreo-managed-databases-and-caches.md similarity index 100% rename from en/docs/manage-databases-and-caches/choreo-managed-databases-and-caches.md rename to en/developer-docs/docs/manage-databases-and-caches/choreo-managed-databases-and-caches.md diff --git a/en/docs/manage-databases-and-caches/choreo-managed-mysql-databases.md b/en/developer-docs/docs/manage-databases-and-caches/choreo-managed-mysql-databases.md similarity index 100% rename from en/docs/manage-databases-and-caches/choreo-managed-mysql-databases.md rename to en/developer-docs/docs/manage-databases-and-caches/choreo-managed-mysql-databases.md diff --git a/en/docs/manage-databases-and-caches/choreo-managed-postgresql-databases.md b/en/developer-docs/docs/manage-databases-and-caches/choreo-managed-postgresql-databases.md similarity index 100% rename from en/docs/manage-databases-and-caches/choreo-managed-postgresql-databases.md rename to en/developer-docs/docs/manage-databases-and-caches/choreo-managed-postgresql-databases.md diff --git a/en/docs/manage-message-brokers/choreo-managed-message-brokers.md b/en/developer-docs/docs/manage-message-brokers/choreo-managed-message-brokers.md similarity index 100% rename from en/docs/manage-message-brokers/choreo-managed-message-brokers.md rename to en/developer-docs/docs/manage-message-brokers/choreo-managed-message-brokers.md diff --git a/en/docs/manage-message-brokers/configure-a-kafka-service.md b/en/developer-docs/docs/manage-message-brokers/configure-a-kafka-service.md similarity index 100% rename from en/docs/manage-message-brokers/configure-a-kafka-service.md rename to en/developer-docs/docs/manage-message-brokers/configure-a-kafka-service.md diff --git a/en/docs/manage-message-brokers/create-choreo-managed-kafka-services.md b/en/developer-docs/docs/manage-message-brokers/create-choreo-managed-kafka-services.md similarity index 99% rename from en/docs/manage-message-brokers/create-choreo-managed-kafka-services.md rename to en/developer-docs/docs/manage-message-brokers/create-choreo-managed-kafka-services.md index 3bd7f097e..db82e52e4 100644 --- a/en/docs/manage-message-brokers/create-choreo-managed-kafka-services.md +++ b/en/developer-docs/docs/manage-message-brokers/create-choreo-managed-kafka-services.md @@ -4,7 +4,7 @@ Kafka on Choreo offers fully managed, distributed message broker services across !!! info "Note" - Kafka service creation is available only for paid Choreo users. - - Kafka service billing will be included in your Choreo subscription, with pricing varying based on the service plan of the resources you create. For more details, see [Choreo Platform Services Billing](../references/choreo-platform-services-billing.md). + - Kafka service billing will be included in your Choreo subscription, with pricing varying based on the service plan of the resources you create. For more details, see [Choreo Platform Services Billing](../references/choreo-platform-services-billing-and-upgrades.md#platform-service-billing-information). ## Create a Choreo-managed Kafka service diff --git a/en/docs/manage-message-brokers/monitor-a-kafka-service.md b/en/developer-docs/docs/manage-message-brokers/monitor-a-kafka-service.md similarity index 100% rename from en/docs/manage-message-brokers/monitor-a-kafka-service.md rename to en/developer-docs/docs/manage-message-brokers/monitor-a-kafka-service.md diff --git a/en/developer-docs/docs/monitoring-and-insights/alerts-overview.md b/en/developer-docs/docs/monitoring-and-insights/alerts-overview.md new file mode 100644 index 000000000..30d9de813 --- /dev/null +++ b/en/developer-docs/docs/monitoring-and-insights/alerts-overview.md @@ -0,0 +1,141 @@ +# Alerts Overview + +This section explains how you can configure alerts for your Choreo components. Setting up alerts allows you to proactively monitor your components ecosystem and take corrective measures when necessary. + +!!! tip + Setting up alerts in only available in the component level. + +## Alert Types + +Choreo supports the following types of alerts to help you monitor and manage your components effectively: + +- [Latency alerts](#latency-alerts) +- [Traffic alerts](#traffic-alerts) +- [Resource alerts](#resource-alerts) +- [Log alerts](#log-alerts) +- [Build failure alerts](#build-failure-alerts) +- [Status code alerts](#status-code-alerts) + +### Latency Alerts + +Latency alerts notify you if the response latency of a component exceeds a predefined threshold in a given time period. This is useful for components that need to meet specific SLAs and for proactively identifying slow components. + +Configurable parameters + +| **Parameter** | **Description** | +|---------------|---------------------------------------------------------------------------------| +| Metric | 99th, 95th, 90th, or 50th percentile. | +| Threshold | Latency in milliseconds (e.g.: 1800). | +| Period | Duration the threshold must be exceeded (e.g.: 5 minutes). | + +### Traffic Alerts + +Traffic alerts notify you when the request count of a component exceeds a predefined threshold. This is useful for managing components with backend traffic limits or monetized backends that require proactive scaling based on incoming traffic. + +Configurable parameters + +| **Parameter** | **Description** | +|---------------|---------------------------------------------------------------------------------| +| Threshold | Requests per minute (e.g.: 200). | +| Period | Monitoring window (e.g.: 5 minutes). | + +### Resource Alerts + +Resource alerts notify you when your component’s CPU or memory usage exceeds the defined thresholds. This ensures you can fix the resources allocations early to avoid performance issues or downtimes. + +Configurable parameters + +| **Parameter** | **Description** | +|---------------|---------------------------------------------------------------------------------| +| Metric | CPU or Memory. | +| Threshold | **mCPU** for CPU and **MiB** for Memory(e.g.: 1000). | +| Period | Duration the threshold must be exceeded (e.g.: 5 minutes). | + +!!! Tip + - **CPU**: mCPU (milliCPU) measures CPU usage in fractions of a core, where 1000m = 1 full core. + - **Memory**: MiB (Mebibyte) measures memory in binary units, where 1 MiB = 2^20^ bytes. + +### Log Alerts + +Log alerts trigger notifications when a specific phrase appears **a specific number of times** in your component logs within a defined Time window. This helps to identify recurring issues or critical errors quickly, enabling faster troubleshooting. + +Configurable parameters + +| **Parameter** | **Description** | +|---------------|---------------------------------------------------------------------------------| +| Search Phrase | Keyword or phrase to look for to trigger the alert (e.g.: failed). | +| Count | Minimum number of occurrences to trigger the alert (e.g.: 10). | +| Interval | Time window for counting occurrences (e.g.: 5 minutes). | + +### Build Failure Alerts + +Build failure alerts inform you if a build failure occurs for your component. This is essential for maintaining smooth development workflows. + +### Status Code Alerts + +Status code alert triggers when your component returns specific HTTP error(s) (e.g.: **403** Forbidden, **500** Internal Error). These alerts help to detect issues affecting your component’s availability. + +Configurable parameters + +| **Parameter** | **Description** | +|---------------|---------------------------------------------------------------------------------| +| Status Code | Error code or series (e.g.: 400:Bad Request). | +| Count | Minimum number of occurrences (e.g.: 5). | +| Interval | Time window (e.g.: 5 minutes). | + +!!! note + Status code alerts are only supported for API proxy component types. + +## Configure Alert + +Follow these steps to configure an alert: + +1. Navigate to the component you wish to configure alerts for. + + !!! info + You need to have a scope of **Choreo DevOps** or **Choreo Platform Engineer** inorder to create Alerts. + +2. In the Choreo left menu, click **Observability** and then click **Alerts**. +3. Click **Create Alert Rule** to create a new alert rule. + + ![Create Alert Rule](../assets/img/monitoring-and-insights/alerts/alert-creation.png){.cInlineImage-full} + +4. Select the **[Alert Type](#alert-types)** you want to create. +5. Select the **Environment** you want to create the alert for. +6. Select the **Deployment Track** or **Version** as required for the component. +7. Configure the remaining fields specific to your selected alert type. +8. In the **Emails** field, specify the list of emails that should be notified when the alert is triggered. + + !!! note + - When adding an email, enter the required email and press enter to add it. + - You can add a maximum of 5 email addresses per alert. + +9. You can configure additional parameters in **Advanced Configurations** dropdown as needed, which vary based on your alert type. +10. The **Explanation window** provides a concise summary of the configured alert based on your alert configurations. +11. Click **Create** to save and activate your alert rule. + + !!! info + - You can configure a maximum of 10 alerts per component. + +12. Once successfully added, your alert will be listed in the **Configure Alerts** pane alongside any existing alerts for the component. +13. Each alert can be **edited**, **removed** and **disabled** or **enabled** via this pane. + + !!! note + when editing an alert, you can't edit the **Alert Type**, **Environment** and **Deployment Track**. + +## Alert History & Notifications + +### View Alert History + +You can check the past alerts that have triggered for your component when you click the **Alerts History** pane in Choreo Alerts. You can filter the alert history by **Alert Type**, **Environment**, **Deployment Track** or **Version** and **Time Range**. + +!!! note + When filtering, **API Proxy components** show a **Version** filter and other components display a **Deployment Track** filter, based on their monitoring context. + +You can click on an alert to expand it and see more details of the triggered alert. + +### Email Notifications + +When an alert is triggered, **recipients** added to the alert rule receive an email with **alert details** including a direct **Alert View link** to Choreo console. + +![Email Notification](../assets/img/monitoring-and-insights/alerts/email-notification.png){.cInlineImage-full} diff --git a/en/developer-docs/docs/monitoring-and-insights/cost-optimization.md b/en/developer-docs/docs/monitoring-and-insights/cost-optimization.md new file mode 100644 index 000000000..2c8b14385 --- /dev/null +++ b/en/developer-docs/docs/monitoring-and-insights/cost-optimization.md @@ -0,0 +1,190 @@ +# Choreo Cost Optimization + +## Overview + +The Choreo cost optimization feature provides detailed cost insights across your organization, enabling you to analyze resource utilization and cost efficiency at the Organization, Project, and Component levels. The dashboards provide comprehensive visualizations and actionable recommendations to optimize cloud infrastructure costs while maintaining performance. + +**All metrics, visualizations, and analytics displayed across the Organization, Project, and Component levels reflect data for the current month, from the first day up to the current date.** This provides you with up-to-date insights into your resource utilization and cost efficiency. +Monthly figures show the accumulated data for the current month so far, while comparisons to previous month are also available in some metrics. This approach gives you both immediate visibility into current spending patterns and understanding the trend compared to last month for optimization decisions. + +You can use this information to track ongoing cost optimization efforts and make timely adjustments to your resource allocations within the current billing cycle. + +## Organization Level + +![Organization level dashboard](../assets/img/cost-optimization/OrganizationLevel.png) + +At the Organization level, Choreo provides key insights into overall cost savings and resource efficiency across all your projects. You can view the following metrics and visualizations: + +* **Monthly Savings Summary** + + Monthly savings summary chart + + + This chart visualizes the percentage of cost savings achieved (by manual or automatic application of recommendations) compared to missed savings (potential savings missed due to recommendations not being applied) up to the current date. You should aim to maximize the saved cost and minimize missed savings. + +* **Total Monthly Savings** + + Total monthly savings card + + + This card shows the cost saved in the current month through manual or automatic application of recommendations. It includes a breakdown for Production and Non-Production environments, with a dropdown showing savings for each respective environment. + +* **Monthly Missed Savings** + + Monthly missed savings card + + This card displays the potential cost savings that were missed due to the failure to apply recommendations, whether manually or automatically. It provides a breakdown of these missed savings for both production and non-production environments, listing values for each individual environment. It is recommended to keep these missed savings as minimal as possible. + +* **Annual Savings** + + Annual savings card + + This card shows accumulated savings throughout the year. It combines the savings completed through the end of the previous month with savings achieved up to the present day of the current month. This demonstrates that a fully cost-optimized organization with no savings for the current month has achieved this state by saving costs in previous months. + +* **Monthly CPU and Memory Cost** + + Monthly CPU and Memory cost card + + This card shows the cost incurred for CPU and Memory allocation across all components in your organization. It includes a percentage change compared to the previous month to indicate cost trends. + +* **Estimated Monthly Cost** + + Estimated monthly cost card + + This card shows the forecasted cost at the end of the month, with an environmental breakdown, regardless of which day of the month you view it. + +* **Monthly CPU and Memory Efficiency** + + Monthly CPU and Memory efficiency card + + This card shows the percentage utilization of CPU and Memory compared to allocation. This metric indicates your resource optimization level, which directly reflects cost optimization. The breakdown of CPU and Memory efficiencies provides individual understanding of each resource's optimization. The percentage change shown compares current efficiency to last month's efficiency with an arrow indicating increase or decrease. + +* **Cost Analysis Plot** + + Cost analysis plot + + The plot consists of three lines: + + * **Allocation Cost** - The maximum of Request Cost and Utilization Cost at a given point in time. This is what you're billed for CPU and memory resource costs. + * **Utilization Cost** - The ideal cost that should be billed if no extra resources were allocated. This is typically not achievable in practice as some buffer is needed for uninterrupted service. + * **Optimized Cost** - The cost suggested by the optimization algorithm that provides sufficient buffer for efficient performance while optimizing costs. + + You can filter the view to show All resources, CPU only, or Memory only for time-based cost analysis. + +* **Cost Savings (Deployments Summary)** + + Deployments summary cards + + Under the Cost Savings section, these cards provide a summary of all deployments in your organization: + + * **Under Provisioned Deployments** - Number of deployments with insufficient resource allocation + * **Over Provisioned Deployments** - Number of deployments with over-allocated resources + * **Idle Deployments** - Deployments with no traffic for the last 3 days + * **Auto-optimized deployments** - Number of deployments with auto-optimization enabled + * **Deployments that require attention** - Number of deployments with auto-optimization disabled that have recommendations for manual application + * **Total number of deployments** - Number of active deployments + +* **Cost Savings (Project Summary)** + + Project summary table + + This table under the Cost Savings section includes a summary of all projects in your organization. Each row represents a project with columns showing: + * Saved Cost after applying recommendations automatically/manually + * Actual Cost after Savings + * CPU and Memory Efficiency + * Ratio of Applied Suggestions to total available recommendations + + You can click on any project in this table or use the top navigation to visit the Project Level cost insights. + +## Project Level + +![Project level dashboard](../assets/img/cost-optimization/ProjectLevel.png) + +The Project Level view is similar to the Organization Level, with all monthly metrics focused on the selected project. The charts, cards, plots, and tables follow the same format as the Organization Level. + +An additional feature at this level is the ability to toggle auto-apply for each component in the Cost Savings (Component Summary) table, or for all components. This simplifies the process of enabling auto-application of recommendations across all components in a project. + + Deployments summary cards + + +These toggles enable automatic application of recommendations for all deployments in the selected components. + +## Component Level + +![Component level dashboard](../assets/img/cost-optimization/ComponentLevel.png) + +The Component Level differs from both Organization and Project levels. At the Component Level, you can access the release level through both deployment track (version) and environment configuration as shown: + + Release selection + +At the Release Level within the Component Level, you can view: + +* **Component details and Optimization Configurations** + + Component details card + + This card shows configuration data for the deployment, including number of replicas, scale to zero settings, and horizontal pod auto-scaling that can be configured in DevOps. + + #### Optimization Configurations + Under the Optimization Configurations section, you can configure how Choreo applies cost optimization recommendations: + + Auto Apply Recommendations: + + When enabled, this toggle automatically implements resource right-sizing recommendations daily. Every 24 hours the system automatically checks if the release has any recommendations that would save more than $0.01, and if found, applies them without requiring manual intervention. This feature helps maintain continuous cost efficiency without constant monitoring. + + + Safety Buffer: + + This setting determines how conservatively the optimization algorithm calculates resource recommendations: + + Low: Adds a 10% buffer above the calculated resource requirements, which maximizes cost savings but provides less headroom for unexpected traffic spikes + + High: Adds a 20% buffer above the calculated resource requirements, offering more capacity for handling unexpected load increases - recommended for production environments + + + + The Safety Buffer setting helps you balance between maximum cost efficiency and maintaining reliable performance. For mission-critical applications or services with variable workloads, the High setting provides additional capacity to handle sudden traffic increases, while the Low setting is suitable for predictable workloads where you want to optimize costs more aggressively. + These configurations allow you to tailor the optimization behavior to your specific needs, balancing cost-saving opportunities with operational requirements at the component level. + +* **Monthly Cost, Missed Savings, Efficiency and Estimated Cost** + + Component metrics cards + + These cards summarize the cost and resource metrics similar to those at the Organization and Project levels. + +* **CPU Metrics Analysis** + + CPU metrics chart + +* **Memory Metrics Analysis** + + Memory metrics chart + +* **Recommendations** + + Memory metrics chart + + The system provides **automated** and **manual** recommendations for cost reduction. + +### Optimization Types + +* **Resource Right-Sizing** + * Suggests optimized CPU and memory limits + * Provides potential cost savings per adjustment + +* **Enable Scale to Zero** + * Stops a component when no requests are being served + * Reduces idle infrastructure costs + +* **Stop Deployment** + * Identifies and halts unused deployments + * Prevents unnecessary spending on unused resources + +### Applying Recommendations + +* **Manually Apply**: You can review and apply suggestions individually +* **Auto-Apply Toggle**: Enables automatic cost optimizations for projects/components + +## Conclusion + +The Choreo Cost Optimization feature helps you improve cloud resource efficiency by providing insights and recommendations at various levels. With interactive visualizations, automated recommendations, and optimization tracking, you can reduce infrastructure costs while maintaining performance. diff --git a/en/docs/monitoring-and-insights/delivery-insights/configure-dora-metrics.md b/en/developer-docs/docs/monitoring-and-insights/delivery-insights/configure-dora-metrics.md similarity index 96% rename from en/docs/monitoring-and-insights/delivery-insights/configure-dora-metrics.md rename to en/developer-docs/docs/monitoring-and-insights/delivery-insights/configure-dora-metrics.md index ce1eed1f8..73f20788f 100644 --- a/en/docs/monitoring-and-insights/delivery-insights/configure-dora-metrics.md +++ b/en/developer-docs/docs/monitoring-and-insights/delivery-insights/configure-dora-metrics.md @@ -16,11 +16,10 @@ Choreo enables two DORA metrics by default; deployment frequency and lead time f To configure the CIO dashboard by enabling the other two metrics, follow the steps below: -1. Sign in to Choreo using your Google, GitHub, or Microsoft account. -2. On the left navigation menu, click **Delivery Insights**. -3. Click on the **DORA Metrics** tab. -4. Scroll to the bottom of the dashboard and click **Configure**. -5. Select your incident management system. Currently, Choreo only supports GitHub. +1. Sign in to Choreo using your Google, GitHub, or Microsoft account. +2. On the left navigation menu, click **Insights** and then click **Delivery**. +3. Scroll to the bottom of the dashboard and click **Configure**. +4. Select your incident management system. Currently, Choreo only supports GitHub. ## Configuring GitHub as the incident management system diff --git a/en/docs/monitoring-and-insights/delivery-insights/view-dora-metrics.md b/en/developer-docs/docs/monitoring-and-insights/delivery-insights/view-dora-metrics.md similarity index 100% rename from en/docs/monitoring-and-insights/delivery-insights/view-dora-metrics.md rename to en/developer-docs/docs/monitoring-and-insights/delivery-insights/view-dora-metrics.md diff --git a/en/docs/monitoring-and-insights/generate-custom-reports.md b/en/developer-docs/docs/monitoring-and-insights/generate-custom-reports.md similarity index 100% rename from en/docs/monitoring-and-insights/generate-custom-reports.md rename to en/developer-docs/docs/monitoring-and-insights/generate-custom-reports.md diff --git a/en/docs/monitoring-and-insights/insights-overview.md b/en/developer-docs/docs/monitoring-and-insights/insights-overview.md similarity index 99% rename from en/docs/monitoring-and-insights/insights-overview.md rename to en/developer-docs/docs/monitoring-and-insights/insights-overview.md index d59e39294..6fef22391 100644 --- a/en/docs/monitoring-and-insights/insights-overview.md +++ b/en/developer-docs/docs/monitoring-and-insights/insights-overview.md @@ -16,7 +16,7 @@ By leveraging these insights, businesses can make informed decisions to enhance ## View insights -To view usage insights, go to the [Choreo Console](https://console.choreo.dev/) and click **Usage Insights** in the left navigation menu. +To view usage insights, go to the [Choreo Console](https://console.choreo.dev/) and click **Insights** and then click **Usage** in the left navigation menu. If you are viewing insights on the Choreo platform at the organization level, note the following: diff --git a/en/docs/monitoring-and-insights/integrate-choreo-with-moesif.md b/en/developer-docs/docs/monitoring-and-insights/integrate-choreo-with-moesif.md similarity index 100% rename from en/docs/monitoring-and-insights/integrate-choreo-with-moesif.md rename to en/developer-docs/docs/monitoring-and-insights/integrate-choreo-with-moesif.md diff --git a/en/docs/monitoring-and-insights/logs/view-pdp-logs.md b/en/developer-docs/docs/monitoring-and-insights/logs/view-pdp-logs.md similarity index 100% rename from en/docs/monitoring-and-insights/logs/view-pdp-logs.md rename to en/developer-docs/docs/monitoring-and-insights/logs/view-pdp-logs.md diff --git a/en/docs/monitoring-and-insights/observability-overview.md b/en/developer-docs/docs/monitoring-and-insights/observability-overview.md similarity index 100% rename from en/docs/monitoring-and-insights/observability-overview.md rename to en/developer-docs/docs/monitoring-and-insights/observability-overview.md diff --git a/en/docs/monitoring-and-insights/view-logs.md b/en/developer-docs/docs/monitoring-and-insights/view-logs.md similarity index 100% rename from en/docs/monitoring-and-insights/view-logs.md rename to en/developer-docs/docs/monitoring-and-insights/view-logs.md diff --git a/en/docs/monitoring-and-insights/work-with-choreo-insights-api/access-the-choreo-insights-api.md b/en/developer-docs/docs/monitoring-and-insights/work-with-choreo-insights-api/access-the-choreo-insights-api.md similarity index 100% rename from en/docs/monitoring-and-insights/work-with-choreo-insights-api/access-the-choreo-insights-api.md rename to en/developer-docs/docs/monitoring-and-insights/work-with-choreo-insights-api/access-the-choreo-insights-api.md diff --git a/en/docs/monitoring-and-insights/work-with-choreo-insights-api/choreo-insights-api.md b/en/developer-docs/docs/monitoring-and-insights/work-with-choreo-insights-api/choreo-insights-api.md similarity index 100% rename from en/docs/monitoring-and-insights/work-with-choreo-insights-api/choreo-insights-api.md rename to en/developer-docs/docs/monitoring-and-insights/work-with-choreo-insights-api/choreo-insights-api.md diff --git a/en/docs/monitoring-and-insights/work-with-choreo-insights-api/graphiql-explorer/asset-manifest.json b/en/developer-docs/docs/monitoring-and-insights/work-with-choreo-insights-api/graphiql-explorer/asset-manifest.json similarity index 100% rename from en/docs/monitoring-and-insights/work-with-choreo-insights-api/graphiql-explorer/asset-manifest.json rename to en/developer-docs/docs/monitoring-and-insights/work-with-choreo-insights-api/graphiql-explorer/asset-manifest.json diff --git a/en/docs/monitoring-and-insights/work-with-choreo-insights-api/graphiql-explorer/favicon.ico b/en/developer-docs/docs/monitoring-and-insights/work-with-choreo-insights-api/graphiql-explorer/favicon.ico similarity index 100% rename from en/docs/monitoring-and-insights/work-with-choreo-insights-api/graphiql-explorer/favicon.ico rename to en/developer-docs/docs/monitoring-and-insights/work-with-choreo-insights-api/graphiql-explorer/favicon.ico diff --git a/en/docs/monitoring-and-insights/work-with-choreo-insights-api/graphiql-explorer/index.html b/en/developer-docs/docs/monitoring-and-insights/work-with-choreo-insights-api/graphiql-explorer/index.html similarity index 100% rename from en/docs/monitoring-and-insights/work-with-choreo-insights-api/graphiql-explorer/index.html rename to en/developer-docs/docs/monitoring-and-insights/work-with-choreo-insights-api/graphiql-explorer/index.html diff --git a/en/docs/monitoring-and-insights/work-with-choreo-insights-api/graphiql-explorer/insight.config.js b/en/developer-docs/docs/monitoring-and-insights/work-with-choreo-insights-api/graphiql-explorer/insight.config.js similarity index 100% rename from en/docs/monitoring-and-insights/work-with-choreo-insights-api/graphiql-explorer/insight.config.js rename to en/developer-docs/docs/monitoring-and-insights/work-with-choreo-insights-api/graphiql-explorer/insight.config.js diff --git a/en/docs/monitoring-and-insights/work-with-choreo-insights-api/graphiql-explorer/manifest.json b/en/developer-docs/docs/monitoring-and-insights/work-with-choreo-insights-api/graphiql-explorer/manifest.json similarity index 100% rename from en/docs/monitoring-and-insights/work-with-choreo-insights-api/graphiql-explorer/manifest.json rename to en/developer-docs/docs/monitoring-and-insights/work-with-choreo-insights-api/graphiql-explorer/manifest.json diff --git a/en/docs/monitoring-and-insights/work-with-choreo-insights-api/graphiql-explorer/static/css/2.dff3c244.chunk.css b/en/developer-docs/docs/monitoring-and-insights/work-with-choreo-insights-api/graphiql-explorer/static/css/2.dff3c244.chunk.css similarity index 100% rename from en/docs/monitoring-and-insights/work-with-choreo-insights-api/graphiql-explorer/static/css/2.dff3c244.chunk.css rename to en/developer-docs/docs/monitoring-and-insights/work-with-choreo-insights-api/graphiql-explorer/static/css/2.dff3c244.chunk.css diff --git a/en/docs/monitoring-and-insights/work-with-choreo-insights-api/graphiql-explorer/static/css/2.dff3c244.chunk.css.map b/en/developer-docs/docs/monitoring-and-insights/work-with-choreo-insights-api/graphiql-explorer/static/css/2.dff3c244.chunk.css.map similarity index 100% rename from en/docs/monitoring-and-insights/work-with-choreo-insights-api/graphiql-explorer/static/css/2.dff3c244.chunk.css.map rename to en/developer-docs/docs/monitoring-and-insights/work-with-choreo-insights-api/graphiql-explorer/static/css/2.dff3c244.chunk.css.map diff --git a/en/docs/monitoring-and-insights/work-with-choreo-insights-api/graphiql-explorer/static/css/main.dd389ba7.chunk.css b/en/developer-docs/docs/monitoring-and-insights/work-with-choreo-insights-api/graphiql-explorer/static/css/main.dd389ba7.chunk.css similarity index 100% rename from en/docs/monitoring-and-insights/work-with-choreo-insights-api/graphiql-explorer/static/css/main.dd389ba7.chunk.css rename to en/developer-docs/docs/monitoring-and-insights/work-with-choreo-insights-api/graphiql-explorer/static/css/main.dd389ba7.chunk.css diff --git a/en/docs/monitoring-and-insights/work-with-choreo-insights-api/graphiql-explorer/static/css/main.dd389ba7.chunk.css.map b/en/developer-docs/docs/monitoring-and-insights/work-with-choreo-insights-api/graphiql-explorer/static/css/main.dd389ba7.chunk.css.map similarity index 100% rename from en/docs/monitoring-and-insights/work-with-choreo-insights-api/graphiql-explorer/static/css/main.dd389ba7.chunk.css.map rename to en/developer-docs/docs/monitoring-and-insights/work-with-choreo-insights-api/graphiql-explorer/static/css/main.dd389ba7.chunk.css.map diff --git a/en/docs/monitoring-and-insights/work-with-choreo-insights-api/graphiql-explorer/static/js/2.e5757962.chunk.js b/en/developer-docs/docs/monitoring-and-insights/work-with-choreo-insights-api/graphiql-explorer/static/js/2.e5757962.chunk.js similarity index 100% rename from en/docs/monitoring-and-insights/work-with-choreo-insights-api/graphiql-explorer/static/js/2.e5757962.chunk.js rename to en/developer-docs/docs/monitoring-and-insights/work-with-choreo-insights-api/graphiql-explorer/static/js/2.e5757962.chunk.js diff --git a/en/docs/monitoring-and-insights/work-with-choreo-insights-api/graphiql-explorer/static/js/2.e5757962.chunk.js.LICENSE.txt b/en/developer-docs/docs/monitoring-and-insights/work-with-choreo-insights-api/graphiql-explorer/static/js/2.e5757962.chunk.js.LICENSE.txt similarity index 100% rename from en/docs/monitoring-and-insights/work-with-choreo-insights-api/graphiql-explorer/static/js/2.e5757962.chunk.js.LICENSE.txt rename to en/developer-docs/docs/monitoring-and-insights/work-with-choreo-insights-api/graphiql-explorer/static/js/2.e5757962.chunk.js.LICENSE.txt diff --git a/en/docs/monitoring-and-insights/work-with-choreo-insights-api/graphiql-explorer/static/js/2.e5757962.chunk.js.map b/en/developer-docs/docs/monitoring-and-insights/work-with-choreo-insights-api/graphiql-explorer/static/js/2.e5757962.chunk.js.map similarity index 100% rename from en/docs/monitoring-and-insights/work-with-choreo-insights-api/graphiql-explorer/static/js/2.e5757962.chunk.js.map rename to en/developer-docs/docs/monitoring-and-insights/work-with-choreo-insights-api/graphiql-explorer/static/js/2.e5757962.chunk.js.map diff --git a/en/docs/monitoring-and-insights/work-with-choreo-insights-api/graphiql-explorer/static/js/main.78fb288a.chunk.js b/en/developer-docs/docs/monitoring-and-insights/work-with-choreo-insights-api/graphiql-explorer/static/js/main.78fb288a.chunk.js similarity index 100% rename from en/docs/monitoring-and-insights/work-with-choreo-insights-api/graphiql-explorer/static/js/main.78fb288a.chunk.js rename to en/developer-docs/docs/monitoring-and-insights/work-with-choreo-insights-api/graphiql-explorer/static/js/main.78fb288a.chunk.js diff --git a/en/docs/monitoring-and-insights/work-with-choreo-insights-api/graphiql-explorer/static/js/main.78fb288a.chunk.js.map b/en/developer-docs/docs/monitoring-and-insights/work-with-choreo-insights-api/graphiql-explorer/static/js/main.78fb288a.chunk.js.map similarity index 100% rename from en/docs/monitoring-and-insights/work-with-choreo-insights-api/graphiql-explorer/static/js/main.78fb288a.chunk.js.map rename to en/developer-docs/docs/monitoring-and-insights/work-with-choreo-insights-api/graphiql-explorer/static/js/main.78fb288a.chunk.js.map diff --git a/en/docs/monitoring-and-insights/work-with-choreo-insights-api/graphiql-explorer/static/js/runtime-main.8245b2d9.js b/en/developer-docs/docs/monitoring-and-insights/work-with-choreo-insights-api/graphiql-explorer/static/js/runtime-main.8245b2d9.js similarity index 100% rename from en/docs/monitoring-and-insights/work-with-choreo-insights-api/graphiql-explorer/static/js/runtime-main.8245b2d9.js rename to en/developer-docs/docs/monitoring-and-insights/work-with-choreo-insights-api/graphiql-explorer/static/js/runtime-main.8245b2d9.js diff --git a/en/docs/monitoring-and-insights/work-with-choreo-insights-api/graphiql-explorer/static/js/runtime-main.8245b2d9.js.map b/en/developer-docs/docs/monitoring-and-insights/work-with-choreo-insights-api/graphiql-explorer/static/js/runtime-main.8245b2d9.js.map similarity index 100% rename from en/docs/monitoring-and-insights/work-with-choreo-insights-api/graphiql-explorer/static/js/runtime-main.8245b2d9.js.map rename to en/developer-docs/docs/monitoring-and-insights/work-with-choreo-insights-api/graphiql-explorer/static/js/runtime-main.8245b2d9.js.map diff --git a/en/docs/monitoring-and-insights/work-with-choreo-insights-api/graphiql-explorer/static/media/gilmer-bold.1b0f0f29.eot b/en/developer-docs/docs/monitoring-and-insights/work-with-choreo-insights-api/graphiql-explorer/static/media/gilmer-bold.1b0f0f29.eot similarity index 100% rename from en/docs/monitoring-and-insights/work-with-choreo-insights-api/graphiql-explorer/static/media/gilmer-bold.1b0f0f29.eot rename to en/developer-docs/docs/monitoring-and-insights/work-with-choreo-insights-api/graphiql-explorer/static/media/gilmer-bold.1b0f0f29.eot diff --git a/en/docs/monitoring-and-insights/work-with-choreo-insights-api/graphiql-explorer/static/media/gilmer-bold.703ca0a7.woff2 b/en/developer-docs/docs/monitoring-and-insights/work-with-choreo-insights-api/graphiql-explorer/static/media/gilmer-bold.703ca0a7.woff2 similarity index 100% rename from en/docs/monitoring-and-insights/work-with-choreo-insights-api/graphiql-explorer/static/media/gilmer-bold.703ca0a7.woff2 rename to en/developer-docs/docs/monitoring-and-insights/work-with-choreo-insights-api/graphiql-explorer/static/media/gilmer-bold.703ca0a7.woff2 diff --git a/en/docs/monitoring-and-insights/work-with-choreo-insights-api/graphiql-explorer/static/media/gilmer-bold.9cf9669b.ttf b/en/developer-docs/docs/monitoring-and-insights/work-with-choreo-insights-api/graphiql-explorer/static/media/gilmer-bold.9cf9669b.ttf similarity index 100% rename from en/docs/monitoring-and-insights/work-with-choreo-insights-api/graphiql-explorer/static/media/gilmer-bold.9cf9669b.ttf rename to en/developer-docs/docs/monitoring-and-insights/work-with-choreo-insights-api/graphiql-explorer/static/media/gilmer-bold.9cf9669b.ttf diff --git a/en/docs/monitoring-and-insights/work-with-choreo-insights-api/graphiql-explorer/static/media/gilmer-bold.fb7355ad.woff b/en/developer-docs/docs/monitoring-and-insights/work-with-choreo-insights-api/graphiql-explorer/static/media/gilmer-bold.fb7355ad.woff similarity index 100% rename from en/docs/monitoring-and-insights/work-with-choreo-insights-api/graphiql-explorer/static/media/gilmer-bold.fb7355ad.woff rename to en/developer-docs/docs/monitoring-and-insights/work-with-choreo-insights-api/graphiql-explorer/static/media/gilmer-bold.fb7355ad.woff diff --git a/en/docs/monitoring-and-insights/work-with-choreo-insights-api/graphiql-explorer/static/media/gilmer-medium.18a9997c.woff2 b/en/developer-docs/docs/monitoring-and-insights/work-with-choreo-insights-api/graphiql-explorer/static/media/gilmer-medium.18a9997c.woff2 similarity index 100% rename from en/docs/monitoring-and-insights/work-with-choreo-insights-api/graphiql-explorer/static/media/gilmer-medium.18a9997c.woff2 rename to en/developer-docs/docs/monitoring-and-insights/work-with-choreo-insights-api/graphiql-explorer/static/media/gilmer-medium.18a9997c.woff2 diff --git a/en/docs/monitoring-and-insights/work-with-choreo-insights-api/graphiql-explorer/static/media/gilmer-medium.721edb3d.ttf b/en/developer-docs/docs/monitoring-and-insights/work-with-choreo-insights-api/graphiql-explorer/static/media/gilmer-medium.721edb3d.ttf similarity index 100% rename from en/docs/monitoring-and-insights/work-with-choreo-insights-api/graphiql-explorer/static/media/gilmer-medium.721edb3d.ttf rename to en/developer-docs/docs/monitoring-and-insights/work-with-choreo-insights-api/graphiql-explorer/static/media/gilmer-medium.721edb3d.ttf diff --git a/en/docs/monitoring-and-insights/work-with-choreo-insights-api/graphiql-explorer/static/media/gilmer-medium.8feb26bf.eot b/en/developer-docs/docs/monitoring-and-insights/work-with-choreo-insights-api/graphiql-explorer/static/media/gilmer-medium.8feb26bf.eot similarity index 100% rename from en/docs/monitoring-and-insights/work-with-choreo-insights-api/graphiql-explorer/static/media/gilmer-medium.8feb26bf.eot rename to en/developer-docs/docs/monitoring-and-insights/work-with-choreo-insights-api/graphiql-explorer/static/media/gilmer-medium.8feb26bf.eot diff --git a/en/docs/monitoring-and-insights/work-with-choreo-insights-api/graphiql-explorer/static/media/gilmer-medium.9eb8c454.woff b/en/developer-docs/docs/monitoring-and-insights/work-with-choreo-insights-api/graphiql-explorer/static/media/gilmer-medium.9eb8c454.woff similarity index 100% rename from en/docs/monitoring-and-insights/work-with-choreo-insights-api/graphiql-explorer/static/media/gilmer-medium.9eb8c454.woff rename to en/developer-docs/docs/monitoring-and-insights/work-with-choreo-insights-api/graphiql-explorer/static/media/gilmer-medium.9eb8c454.woff diff --git a/en/docs/monitoring-and-insights/work-with-choreo-insights-api/graphiql-explorer/static/media/gilmer-regular.34195eed.woff b/en/developer-docs/docs/monitoring-and-insights/work-with-choreo-insights-api/graphiql-explorer/static/media/gilmer-regular.34195eed.woff similarity index 100% rename from en/docs/monitoring-and-insights/work-with-choreo-insights-api/graphiql-explorer/static/media/gilmer-regular.34195eed.woff rename to en/developer-docs/docs/monitoring-and-insights/work-with-choreo-insights-api/graphiql-explorer/static/media/gilmer-regular.34195eed.woff diff --git a/en/docs/monitoring-and-insights/work-with-choreo-insights-api/graphiql-explorer/static/media/gilmer-regular.4e0de531.ttf b/en/developer-docs/docs/monitoring-and-insights/work-with-choreo-insights-api/graphiql-explorer/static/media/gilmer-regular.4e0de531.ttf similarity index 100% rename from en/docs/monitoring-and-insights/work-with-choreo-insights-api/graphiql-explorer/static/media/gilmer-regular.4e0de531.ttf rename to en/developer-docs/docs/monitoring-and-insights/work-with-choreo-insights-api/graphiql-explorer/static/media/gilmer-regular.4e0de531.ttf diff --git a/en/docs/monitoring-and-insights/work-with-choreo-insights-api/graphiql-explorer/static/media/gilmer-regular.ac841c91.woff2 b/en/developer-docs/docs/monitoring-and-insights/work-with-choreo-insights-api/graphiql-explorer/static/media/gilmer-regular.ac841c91.woff2 similarity index 100% rename from en/docs/monitoring-and-insights/work-with-choreo-insights-api/graphiql-explorer/static/media/gilmer-regular.ac841c91.woff2 rename to en/developer-docs/docs/monitoring-and-insights/work-with-choreo-insights-api/graphiql-explorer/static/media/gilmer-regular.ac841c91.woff2 diff --git a/en/docs/monitoring-and-insights/work-with-choreo-insights-api/graphiql-explorer/static/media/gilmer-regular.dadefd19.eot b/en/developer-docs/docs/monitoring-and-insights/work-with-choreo-insights-api/graphiql-explorer/static/media/gilmer-regular.dadefd19.eot similarity index 100% rename from en/docs/monitoring-and-insights/work-with-choreo-insights-api/graphiql-explorer/static/media/gilmer-regular.dadefd19.eot rename to en/developer-docs/docs/monitoring-and-insights/work-with-choreo-insights-api/graphiql-explorer/static/media/gilmer-regular.dadefd19.eot diff --git a/en/docs/monitoring-and-insights/work-with-choreo-insights-api/graphiql-explorer/static/media/logout.ab831324.svg b/en/developer-docs/docs/monitoring-and-insights/work-with-choreo-insights-api/graphiql-explorer/static/media/logout.ab831324.svg similarity index 100% rename from en/docs/monitoring-and-insights/work-with-choreo-insights-api/graphiql-explorer/static/media/logout.ab831324.svg rename to en/developer-docs/docs/monitoring-and-insights/work-with-choreo-insights-api/graphiql-explorer/static/media/logout.ab831324.svg diff --git a/en/docs/page-not-found.md b/en/developer-docs/docs/page-not-found.md similarity index 100% rename from en/docs/page-not-found.md rename to en/developer-docs/docs/page-not-found.md diff --git a/en/developer-docs/docs/quick-start-guides/deploy-a-web-application-that-consumes-a-backend-service.md b/en/developer-docs/docs/quick-start-guides/deploy-a-web-application-that-consumes-a-backend-service.md new file mode 100644 index 000000000..cb7262179 --- /dev/null +++ b/en/developer-docs/docs/quick-start-guides/deploy-a-web-application-that-consumes-a-backend-service.md @@ -0,0 +1,288 @@ +# Deploy a Web Application that Consumes a Backend Service + +Choreo is an Internal Developer Platform (IDevP) that simplifies building, deploying, monitoring, and managing cloud-native applications. + +In this guide, you will learn how to: + +- Expose a service endpoint via Choreo. +- Securely consume the service from a web application. +- Use Choreo's managed authentication to set up authentication for your web application without dealing with complex security protocols. + +The sample web application allows users to: +- Sign in and view their reading lists. +- Add books to a reading list. +- Delete books from the reading list. +- Sign out of the application. + +This guide walks you through the following steps: + +1. Deploy and test a service component. +2. Create a web application to consume the service. +3. Create a connection to the deployed service. +4. Enable managed authentication and deploy the web application. +5. Consume the deployed service via the web application. + +## Prerequisites + +1. GitHub account: Fork the [Choreo sample book list app repository](https://github.com/wso2/choreo-sample-book-list-app), which contains the sample for this guide. + +2. If you're signing in to the Choreo Console for the first time, create an organization: + 1. Go to [https://console.choreo.dev/](https://console.choreo.dev/) and sign in using your Google, GitHub, or Microsoft account. + 2. Enter a unique organization name. For example, `Stark Industries`. + 3. Read and accept the privacy policy and terms of use. + 4. Click **Create**. + + This creates the organization and opens the organization home page. + +## Step 1: Create a project + +1. Go to [https://console.choreo.dev/](https://console.choreo.dev/) and sign in. This opens the organization home page. +2. On the organization home page, click **+ Create Project**. +3. Enter the following details: + + !!! tip + The **Name** field must be unique and cannot be changed after creation. + + | **Field** | **Value** | + |--------------------------|-----------------------| + | **Project Display Name** | Sample project | + | **Name** | sample-project | + | **Project Description** | My sample project | + +4. Click **Create**. This creates the project and opens the project home page. + +## Step 2: Connect your sample repository and configure the service + +1. On the project home page, click **Start** under **Create Multiple Components**. +2. Go to the **GitHub** tab. +3. Click **Authorize with GitHub** to connect Choreo to your GitHub account. If you haven't connected your GitHub repository to Choreo, enter your credentials and select the repository you forked earlier to install the [Choreo GitHub App](https://github.com/marketplace/choreo-apps). + + Alternatively, paste the [Choreo sample book list app repository](https://github.com/wso2/choreo-sample-book-list-app) URL in the **Provide Repository URL** field. However, enabling [**Auto Deploy**](https://wso2.com/choreo/docs/choreo-concepts/ci-cd/#deploy) requires authorizing the repository with the [Choreo GitHub App](https://github.com/marketplace/choreo-apps). + + !!! note + The **Choreo GitHub App** requires: + - Read and write access to code and pull requests. + - Read access to issues and metadata. + + You can [revoke access](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/reviewing-your-authorized-integrations#reviewing-your-authorized-github-apps) at any time. Write access is only used for sending pull requests; Choreo will not push changes directly to your repository. + +4. Enter the following information: + + | **Field** | **Value** | + |------------------------------|-----------------------------| + | **Organization** | Your GitHub account | + | **Repository** | choreo-sample-book-list-app | + | **Branch** | main | + +5. In the **Add Component Directories** pane under **Configure Components**, click the **+** icon next to `reading-list-service`. +6. In the **Component Configuration** dialog, specify the following: + + | **Field** | **Value** | + |---------------------------|-----------------------------------------------| + | **Component Display Name**| Reading List Service | + | **Component Name** | reading-list-service | + | **Path** | reading-list-service | + | **Component Type** | Service | + | **Buildpack** | NodeJS | + | **Language Version** | 20.x.x | + +7. Click **Save**. This adds the `Reading List Service` component to the **Configured Components** pane. +8. Click **Finish**. This initializes the service with the implementation from your GitHub repository and takes you to the project home page. + + You can see the `Reading List Service` component listed under **Component Listing** on the project home page. + +## Step 3: Build the service + +1. On the project home page, click the `Reading List Service` component under **Component Listing**. This takes you to the component overview page. +2. In the left navigation menu, click **Build**. +3. In the **Builds** pane, click **Build Latest**. + + !!! note + The build process may take some time. You can track progress in the **Build Details** pane. Once complete, the build status changes to **Success**. + +## Step 4: Deploy the service + +1. In the left navigation menu, click **Deploy**. +2. In the **Set Up** card, click **Configure & Deploy**. +3. In the **Environment Configurations** pane, click **Next** to skip the configuration. +4. In the **File Mount** pane, click **Next** to skip the configuration. +5. In the **Endpoint Details** pane, verify that **Network Visibility** is set to **Public**. This securely exposes the endpoint for consumption. +6. Click **Deploy**. This deploys the service to the development environment and lists it in the [Choreo Marketplace](../choreo-concepts/choreo-marketplace.md). + +## Step 5: Test the service + +1. In the Choreo Console left navigation menu, click **Test** and then click **Console**. +2. In the OpenAPI Console, select **Development** from the environment drop-down. +3. In the **Endpoint** list, select **Books REST Endpoint**. +4. Expand the **GET/books** method, click **Try it out**, then click **Execute**. +5. Check the **Server Response** section. You will see an empty response. You can add an entry using the POST method and retry the **GET/books** method. +6. Expand the **POST/books** method and click **Try it out**. +7. Update the request body with the following values: + + | **Parameter** | **Value** | + |---------------|---------------| + | **author** | Bram Stoker | + | **status** | to_read | + | **title** | Dracula | + + The request body should look like this: + + ```json + { + "author": "Bram Stoker", + "status": "to_read", + "title": "Dracula" + } + ``` + +8. Click **Execute**. + + Check the **Server Response** section. On successful invocation, you will receive the `201` HTTP code. + +You can also try out the **GET** and **DELETE** methods. + +## Step 6: Consume the service + +Now that the `Reading List Service` is deployed and available in the Choreo Marketplace, you can discover and consume it. In this section, you will deploy a front-end application to interact with the service. + +### Step 6.1: Create a web application to consume the service + +1. In the Choreo Console header, click the **Project** list and select the project you created in Step 1. +2. On the project home page, click **+ Create** under **Component Listing**. +3. Click the **Web Application** card. +4. Click **Authorize with GitHub** to connect Choreo to your GitHub account. If you haven't connected your GitHub repository to Choreo, enter your credentials and select the repository you forked earlier to install the [Choreo GitHub App](https://github.com/marketplace/choreo-apps). + + Alternatively, select the **Use Public GitHub Repository** option and paste the [Choreo sample Book List Service repository](https://github.com/wso2/choreo-sample-book-list-service) URL in the **Provide Repository URL** field. However, enabling [**Auto Deploy**](https://wso2.com/choreo/docs/choreo-concepts/ci-cd/#deploy) requires authorizing the repository with the [Choreo GitHub App](https://github.com/marketplace/choreo-apps). + + !!! note + The **Choreo GitHub App** requires: + + - Read and write access to code and pull requests. + - Read access to issues and metadata. + + You can [revoke access](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/reviewing-your-authorized-integrations#reviewing-your-authorized-github-apps) at any time. Write access is only used for sending pull requests; Choreo will not push changes directly to your repository. + +5. Enter the following information: + + | **Field** | **Description** | + |-----------------------|----------------------------------| + | **Organization** | Your GitHub account | + | **Repository** | choreo-sample-book-list-app | + | **Branch** | main | + | **Component Directory** | /choreo-sample-book-list-app/reading-list-front-end-with-managed-auth | + +6. Select **React** as the buildpack because the sample front-end application is a React application built with Vite. +7. Enter the following details: + + | **Field** | **Value** | + |-----------------------|-------------------------| + | **Build Command** | npm install && npm run build | + | **Build Path** | dist | + | **Node Version** | 18 | + +8. Enter the following details: + + !!! info + The **Component Name** field must be unique and cannot be changed after creation. + + | **Field** | **Value** | + |---------------------------|------------------------------------------------| + | **Component Display Name**| Reading List Web App | + | **Component Name** | reading-list-web-app | + | **Description** | Front-end application for the reading list service | + + +9. Click **Create**. This initializes the component with the implementation from your GitHub repository and takes you to the **Overview** page of the component. + +### Step 6.2: Create a connection between the web application and the deployed service + +A connection allows you to integrate the service with other services or external resources. For more information, refer to the [Connection](../choreo-concepts/connections.md) documentation. + +1. In the left navigation menu, click **Dependencies** and then click **Connections**. +2. Click **+ Create**. +3. In the **Select a Service** pane, click `Reading List Service`. +4. Specify the following: + + | **Field** | **Value** | + |------------------|-------------------------------| + | **Name** | Reading List Connection | + | **Description** | Connection to the reading list| + +5. Click **Create**. This creates the connection and displays the service URL for the Development environment. Copy the service URL for later use. + +### Step 6.3: Build the web application component + +1. In the left navigation menu, click **Build**. +2. In the **Builds** pane, click **Build Latest**. + + !!! note + The build process may take some time. You can track progress in the **Build Details** pane. Once complete, the build status changes to **Success**. + +### Step 6.4: Configure and deploy the web application + +1. In the left navigation menu, click **Deploy**. +2. In the **Set Up** card, click **Configure and Deploy**. +3. In the `config.js` file mount, replace `` with the value you copied when creating the connection to the `Reading List Service` in [Step 6.2](#step-62-create-a-connection-between-the-web-application-and-the-deployed-service). + + ```javascript + window.configs = { + apiUrl: '', + }; + ``` + + !!! tip + You can refer to the configuration file mounted at `/app/public` as `./public/config.js` within your web application. + +4. Click **Next** to open the **Authentication** pane. +5. Under **Authentication Settings**, ensure that **Managed authentication with Choreo** is enabled. + + !!! tip + Managed authentication is enabled by default for **React**, **Angular**, or **Vue.js** buildpacks. + +6. Specify the following: + + | **Field** | **Value** | + |---------------------|------------| + | **Post Login Path** | / | + | **Post Logout Path**| / | + | **Error Path** | / | + +7. Under **Manage Users**, click **+ Create**. +8. Click **Create** to proceed with the default username and password. Copy the credentials for testing. + + !!! tip + By default, your test user base consists of a demo user. For instructions on modifying the test user base, see [Configure a User Store with the Built-In Identity Provider](../administer/configure-a-user-store-with-built-in-idp.md). + +9. In the **Authentication** pane, click **Deploy**. The deployment may take a few minutes. +10. Once deployed, copy the **Web App URL** from the development environment card. +11. Navigate to the web app URL to verify that the web application is hosted successfully. + +## Step 7: Test the front-end application + +1. Access the front-end application via its web URL. +2. Click **Login** and sign in with the credentials you created. + + The application opens as follows: + + ![Front-end application](../assets/img/quick-start-guides/front-end-application.png){.cInlineImage-half} + +3. Add three new reading items with different statuses. For example: + + | **Title** | **Author** | **Status** | + |---------------------------|-------------------|------------| + | The Museum of Innocence | Orhan Pamuk | reading | + | The Remains of the Day | Kazuo Ishiguro | to_read | + | David Copperfield | Charles Dickens | read | + + To add each record: + 1. Click **+ Add New**. + 2. Enter values for the **Name**, **Author**, and **Status** fields. + 3. Click **Save**. + + To delete a reading list item, click **Delete**. + +To verify that the reading list is personalized for each user, sign in as a different user. The reading list items you entered will not appear for the other user. + +Congratulations! You have successfully exposed a service endpoint via Choreo and securely consumed it from a web application. + +After testing your service and web application, explore other Choreo features like [managing](../api-management/lifecycle-management.md), [observing](../monitoring-and-insights/observability-overview.md), and [DevOps](../devops-and-ci-cd/view-runtime-details.md). diff --git a/en/developer-docs/docs/quick-start-guides/deploy-your-first-service.md b/en/developer-docs/docs/quick-start-guides/deploy-your-first-service.md new file mode 100644 index 000000000..078faa7b2 --- /dev/null +++ b/en/developer-docs/docs/quick-start-guides/deploy-your-first-service.md @@ -0,0 +1,132 @@ +# Deploy Your First Service + +Choreo is an Internal Developer Platform (IDevP) that makes it easy to deploy, monitor, and manage your cloud-native services. This allows you to focus on innovation and implementation. + +With Choreo, you can deploy services written in your preferred programming language in just a few simple steps. + +In this guide, you will: + +- Use a pre-built service that manages a book list. +- Build and deploy the service in Choreo using the `Node.js` buildpack. The service runs on port 8080. +- Test the service. + +For a video tutorial, check out [Deploy Your First Service with Choreo](https://www.youtube.com/watch?v=-qoweQWCiYM). + +## Prerequisites + +1. GitHub account: Fork the [Choreo sample book list service repository](https://github.com/wso2/choreo-sample-book-list-service/), which contains the sample for this guide. + +2. If you're signing in to the Choreo Console for the first time, create an organization: + 1. Go to [https://console.choreo.dev/](https://console.choreo.dev/) and sign in using your Google, GitHub, or Microsoft account. + 2. Enter a unique organization name. For example, `Stark Industries`. + 3. Read and accept the privacy policy and terms of use. + 4. Click **Create**. + + This creates the organization and opens the organization home page. + +### Repository file structure + +Let's review the key files in the sample application: + +!!! note + The file paths are relative to `/`. +| Filepath | Description | +|------------------------|-------------------------------------------------------------------------------| +| `app.mjs` | The Node.js (JavaScript) service code. | +| `.choreo/component.yaml` | Choreo-specific configuration for exposing the service. | +| `openapi.yaml` | OpenAPI contract for the service, required to publish it as a managed API. | + +Let's get started! + +## Step 1: Create a project + +1. Go to [https://console.choreo.dev/](https://console.choreo.dev/) and sign in. This opens the organization home page. +2. On the organization home page, click **+ Create Project**. +3. Enter the following details: + + !!! info + The **Name** field must be unique and cannot be changed after creation. + + | **Field** | **Value** | + |--------------------------|------------------------------------| + | **Project Display Name** | Book List Project | + | **Name** | book-list-project | + | **Project Description** | My sample project | + +4. Click **Create**. This creates the project and takes you to the project home page. + +## Step 2: Create a service component + +1. On the project home page, click **Service** under **Create a Component**. +2. Click **Authorize with GitHub** to connect Choreo to your GitHub account. If you haven't connected your GitHub repository to Choreo, enter your credentials and select the repository you forked earlier to install the [Choreo GitHub App](https://github.com/marketplace/choreo-apps). + + Alternatively, select the **Use Public GitHub Repository** option and paste the [Choreo sample Book List Service repository](https://github.com/wso2/choreo-sample-book-list-service) URL in the **Provide Repository URL** field. However, enabling [**Auto Deploy**](https://wso2.com/choreo/docs/choreo-concepts/ci-cd/#deploy) requires authorizing the repository with the [Choreo GitHub App](https://github.com/marketplace/choreo-apps). + + !!! note + The **Choreo GitHub App** requires: + - Read and write access to code and pull requests. + - Read access to issues and metadata. + + You can [revoke access](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/reviewing-your-authorized-integrations#reviewing-your-authorized-github-apps) at any time. Write access is only used for sending pull requests; Choreo will not push changes directly to your repository. + +3. Enter the following information: + + | **Field** | **Description** | + |-----------------------|----------------------------------| + | **Organization** | Your GitHub account | + | **Repository** | choreo-sample-book-list-service | + | **Branch** | main | + | **Component Directory** | / | + +4. Select the **NodeJS** buildpack. +5. Enter the following details: + + | **Field** | **Description** | + |------------------------------|-------------------| + | **Language Version** | 20.x.x | + +6. Enter the following details for Display name and Description: + + | **Field** | **Value** | + |---------------------------|------------------------| + | **Component Display Name**| Book List | + | **Description** | Gets the book list | + +7. Click **Create**. + +You have successfully created a Service component using the NodeJS buildpack. Now, let's build and deploy the service. + +## Step 3: Build and deploy + +### Step 3.1: Build + +1. On the project home page, click the `Book List` component under **Component Listing**. This takes you to the component overview page. +2. In the left navigation, click **Build**. +3. Click **Build Latest**. + + !!! note + The build process may take some time. You can track progress in the **Build Details** pane. Once complete, the build status changes to **Success**. + +### Step 3.2: Deploy + +1. In the left navigation menu, click **Deploy**. +2. On the **Set Up** card, click **Configure & Deploy**. +3. In the **Environment Configurations** pane, click **Next**. +4. In the **File Mount** pane, click **Next**. +5. Review the **Endpoint Details** and click **Deploy**. + + !!! note + Deployment may take some time. Once complete, the status changes to **Active** on the **Development** environment card. + +## Step 4: Test the service + +1. In the Choreo Console left navigation menu, click **Test** and then click **Console**. +2. In the OpenAPI Console, select **Development** from the environment drop-down. +3. In the **Endpoint** list, select **Books REST Endpoint**. +4. Expand the **GET /books** method and click **Try it out**. +5. Click **Execute**. +6. Check the **Server Response** section. + +You can also try out other methods in the OpenAPI Console. + +After successfully testing your service, explore other Choreo features like [managing](../api-management/lifecycle-management.md), [observing](../monitoring-and-insights/observability-overview.md), and [DevOps](../devops-and-ci-cd/view-runtime-details.md). diff --git a/en/developer-docs/docs/quick-start-guides/deploy-your-first-static-web-application.md b/en/developer-docs/docs/quick-start-guides/deploy-your-first-static-web-application.md new file mode 100644 index 000000000..8eeaab3e3 --- /dev/null +++ b/en/developer-docs/docs/quick-start-guides/deploy-your-first-static-web-application.md @@ -0,0 +1,99 @@ +# Deploy Your First Static Web Application + +Choreo is an internal developer platform as a service that simplifies building, deploying, monitoring, and managing cloud-native applications. It allows developers to focus on innovation and implementation by handling platform complexities. + +In this guide, you will learn how to deploy a static web application using Choreo. The sample application is a simple to-do list where users can add tasks. + +This guide walks you through the following steps: + +1. Create a project. +2. Create a Web Application component and connect it to a GitHub repository. +3. Build the web application. +4. Deploy the web application and access it. + +For a video tutorial, see [Deploy a Static Web App on Choreo](https://www.youtube.com/watch?v=YPBSuLG5l5g). + +## Prerequisites + +1. GitHub account: Fork the [choreo-sample-todo-list-app repository](https://github.com/wso2/choreo-sample-todo-list-app), which contains the sample for this guide. + +2. If you're signing in to the Choreo Console for the first time, create an organization: + 1. Go to [https://console.choreo.dev/](https://console.choreo.dev/) and sign in using your Google, GitHub, or Microsoft account. + 2. Enter a unique organization name. For example, `Stark Industries`. + 3. Read and accept the privacy policy and terms of use. + 4. Click **Create**. + + This creates the organization and opens the organization home page. + +## Step 1: Create a project + +1. Go to [https://console.choreo.dev/](https://console.choreo.dev/) and sign in. This opens the organization home page. +2. On the organization home page, click **+ Create Project**. +3. Enter the following details: + + !!! tip + The **Name** field must be unique and cannot be changed after creation. + + | **Field** | **Value** | + |--------------------------|-----------------------| + | **Project Display Name** | Sample project | + | **Name** | sample-project | + | **Project Description** | My sample project | + +4. Click **Create**. This creates the project and opens the project home page. + +## Step 2: Create a web application component + +1. On the project home page, click **Web Application** under **Create a Component**. +2. Select **Authorize with GitHub** from the **Connect a Git Repository** section to connect Choreo to your GitHub account. If you haven't connected your GitHub repository to Choreo, enter your credentials and select the repository you forked earlier to install the [Choreo GitHub App](https://github.com/marketplace/choreo-apps). + + Alternatively, paste the [choreo-sample-todo-list-app repository](https://github.com/wso2/choreo-sample-todo-list-app) URL in the **Provide Repository URL** field. However, enabling [**Auto Deploy**](https://wso2.com/choreo/docs/choreo-concepts/ci-cd/#deploy) requires authorizing the repository with the [Choreo GitHub App](https://github.com/marketplace/choreo-apps). + + !!! note + The **Choreo GitHub App** requires: + - Read and write access to code and pull requests. + - Read access to issues and metadata. + + You can [revoke access](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/reviewing-your-authorized-integrations#reviewing-your-authorized-github-apps) at any time. Write access is only used for sending pull requests; Choreo will not push changes directly to your repository. + +3. Enter the following information: + + | **Field** | **Value** | + |------------------------------|-----------------------------| + | **Organization** | Your GitHub account | + | **Repository** | choreo-sample-todo-list-app | + | **Branch** | main | + +4. Select **NodeJS** as the **Buildpack**. +5. Enter the following details: + + | **Field** | **Value** | + |------------------------------|-----------------------------| + | **NodeJS Project Directory** | / | + | **Language Version** | 20.x.x | + | **Port** | 8080 | + +6. Enter a unique name and description for the web application. + +7. Click **Create**. Choreo initializes the component with the sample implementation and opens the **Overview** page of the component. + +Now let's build and deploy the web application. + +## Step 3: Build your web application + +1. In the left navigation menu, click **Build**. +2. In the **Builds** pane, click **Build Latest**. + + !!! note + The build process may take some time. You can track progress in the **Build Details** pane. Once complete, the build status changes to **Success**. + +Now you can proceed to deploy your web application. + +## Step 4: Deploy and access your web application + +1. In the left navigation menu, click **Deploy**. +2. In the **Set Up** card, click **Configure and Deploy**. This opens the **Configure & Deploy** pane. In this guide, you do not need to add a file mount. +3. Click **Deploy**. The deployment to the Development environment may take a few minutes. Once complete, the **Deployment Status** will show as **Active** in the **Development** card. +4. To verify that the web application is hosted successfully, click the **Web App URL** on the **Development** card. This takes you to the web application. You can try adding tasks by specifying a task ID and task label. + +After successfully testing your web application, explore other Choreo features like [observability](../monitoring-and-insights/observability-overview.md) and [DevOps](../devops-and-ci-cd/view-runtime-details.md). diff --git a/en/docs/references/choreo-limitations.md b/en/developer-docs/docs/references/choreo-limitations.md similarity index 97% rename from en/docs/references/choreo-limitations.md rename to en/developer-docs/docs/references/choreo-limitations.md index 20b4644a0..bf9fd029d 100644 --- a/en/docs/references/choreo-limitations.md +++ b/en/developer-docs/docs/references/choreo-limitations.md @@ -8,7 +8,7 @@ Below are key limitations when working with APIs in Choreo: |Resource | Limit | |-------------------------------------|---------------------------------------------------------------------------------------------| -| Maximum request payload | 10 MB | +| Maximum request payload | 50 MB | | URL size | 2 KB | | Request header |
  • Request Headers total: 40 KB
  • Max Single Request header: 10 KB
| | Total request duration |
  • Minimum: 10 seconds
  • Default: 1 minute
  • Maximum: 5 minutes
| diff --git a/en/docs/references/choreo-platform-services-billing-and-upgrades.md b/en/developer-docs/docs/references/choreo-platform-services-billing-and-upgrades.md similarity index 100% rename from en/docs/references/choreo-platform-services-billing-and-upgrades.md rename to en/developer-docs/docs/references/choreo-platform-services-billing-and-upgrades.md diff --git a/en/docs/references/faq.md b/en/developer-docs/docs/references/faq.md similarity index 98% rename from en/docs/references/faq.md rename to en/developer-docs/docs/references/faq.md index 761edfa94..ce3ea86cc 100644 --- a/en/docs/references/faq.md +++ b/en/developer-docs/docs/references/faq.md @@ -33,7 +33,7 @@ You can find information about our support plans, including `free`, `basic`, and If you have a log monitoring product or service, such as Azure Monitor, you can use it together with Choreo. Note: The log monitoring tool is not included in the infrastructure cost. ### Q: What is the maximum request payload size supported by Choreo? -Choreo allows a maximum request payload size of 10 MB. +Choreo allows a maximum request payload size of 50 MB. ### Q: What source control software does Choreo support? Choreo now supports GitHub, Bitbucket and GitLab. @@ -58,13 +58,13 @@ When an organization admin onboards a new organization in Choreo, they can choos ## Security and data protection ### Q: How is data managed in Choreo? -Choreo manages data using WSO2 containers and Kubernetes clusters, which provide scalability, resilience, and security. Find out more [here](https://wso2.cachefly.net/wso2/sites/all/2023/pdf/wso2-public-cloud-data-protection-faq.pdf). +Choreo manages data using WSO2 containers and Kubernetes clusters, which provide scalability, resilience, and security. Find out more [here](https://wso2.cachefly.net/wso2/sites/all/trust/wso2-public-cloud-data-protection-faq.pdf). ### Q: What is the WSO2 Subprocessor list? -This is a detailed list of all subprocessors used by WSO2, including their name, location, and purpose. This information is updated frequently to ensure compliance with data protection regulations and is found [here](https://wso2.cachefly.net/wso2/sites/all/2023/pdf/wso2-subprocessor-list.pdf). +This is a detailed list of all subprocessors used by WSO2, including their name, location, and purpose. This information is updated frequently to ensure compliance with data protection regulations and is found [here](https://wso2.cachefly.net/wso2/sites/all/trust/wso2-public-cloud-subprocessor-list.pdf). ### Q: How do we secure WSO2 Private and Public Clouds? -WSO2 uses a range of security controls and design patterns to protect against several threats, including internal attacks, software supply chain attacks, service and platform attacks, and more. Find out more regarding this [here](https://wso2.cachefly.net/wso2/sites/all/2023/pdf/securing-wso2-private-and-public-clouds.pdf). +WSO2 uses a range of security controls and design patterns to protect against several threats, including internal attacks, software supply chain attacks, service and platform attacks, and more. For more details, see [Cloud Security Process](https://security.docs.wso2.com/en/latest/security-processes/cloud-security-process/). ### Q: How can I connect a Choreo component with a protected third-party application? To connect a Choreo component with a third-party application, it is necessary to establish seamless communication between the component and the protected third-party application, especially when connecting to external databases like MySQL, MSSQL, PGSQL, Oracle DB, etc. diff --git a/en/docs/references/private-data-plane-management-models.md b/en/developer-docs/docs/references/private-data-plane-management-models.md similarity index 100% rename from en/docs/references/private-data-plane-management-models.md rename to en/developer-docs/docs/references/private-data-plane-management-models.md diff --git a/en/docs/references/private-data-plane-security-levels.md b/en/developer-docs/docs/references/private-data-plane-security-levels.md similarity index 100% rename from en/docs/references/private-data-plane-security-levels.md rename to en/developer-docs/docs/references/private-data-plane-security-levels.md diff --git a/en/docs/references/troubleshoot-choreo.md b/en/developer-docs/docs/references/troubleshoot-choreo.md similarity index 100% rename from en/docs/references/troubleshoot-choreo.md rename to en/developer-docs/docs/references/troubleshoot-choreo.md diff --git a/en/docs/resources/kubernetes-upgrade-notice.md b/en/developer-docs/docs/resources/kubernetes-upgrade-notice.md similarity index 100% rename from en/docs/resources/kubernetes-upgrade-notice.md rename to en/developer-docs/docs/resources/kubernetes-upgrade-notice.md diff --git a/en/docs/search-results.html b/en/developer-docs/docs/search-results.html similarity index 100% rename from en/docs/search-results.html rename to en/developer-docs/docs/search-results.html diff --git a/en/docs/testing/test-apis-with-choreo-apichat.md b/en/developer-docs/docs/testing/test-apis-with-choreo-apichat.md similarity index 100% rename from en/docs/testing/test-apis-with-choreo-apichat.md rename to en/developer-docs/docs/testing/test-apis-with-choreo-apichat.md diff --git a/en/docs/testing/test-apis-with-curl.md b/en/developer-docs/docs/testing/test-apis-with-curl.md similarity index 100% rename from en/docs/testing/test-apis-with-curl.md rename to en/developer-docs/docs/testing/test-apis-with-curl.md diff --git a/en/docs/testing/test-components-with-test-runner.md b/en/developer-docs/docs/testing/test-components-with-test-runner.md similarity index 85% rename from en/docs/testing/test-components-with-test-runner.md rename to en/developer-docs/docs/testing/test-components-with-test-runner.md index e59e634a2..352af7b1d 100644 --- a/en/docs/testing/test-components-with-test-runner.md +++ b/en/developer-docs/docs/testing/test-components-with-test-runner.md @@ -23,21 +23,9 @@ You can develop tests in a language of your choice and execute them within the C 1. Go to [https://console.choreo.dev/](https://console.choreo.dev/) and sign in. This opens the project home page. 2. Click **+Create** in the **Component Listing** section. 3. Click the **Test Runner** card. -4. Enter a display name, unique name, and description for the test runner component. For this guide, enter the following values: - - !!! info - In the **Component Name** field, you must specify a name to uniquely identify the component in various contexts. The value is editable only at the time you create the component. You cannot change the name after you create the component. - - | Field | Value | - | -------------------------|-------------------------------- | - | Component Display Name | `Go Test Runner` | - | Component Name | `go-test-runner` | - | Description | `Test Runner implemented in Go` | - -5. Go to the **GitHub** tab. 6. To allow Choreo to connect to your GitHub account, click **Authorize with GitHub**. If you have not already connected your GitHub repository to Choreo, enter your GitHub credentials and select the repository you created in the prerequisites section to install the [Choreo GitHub App](https://github.com/marketplace/choreo-apps). - Alternatively, you can paste the [Choreo samples repository](https://github.com/wso2/choreo-samples) URL in the **Provide Repository URL** field to connect to it without requiring authorization from the [Choreo Apps](https://github.com/marketplace/choreo-apps) GitHub application. However, authorizing the repository with the [Choreo GitHub App](https://github.com/marketplace/choreo-apps) is necessary if you want to enable [**Auto Deploy**](https://wso2.com/choreo/docs/choreo-concepts/ci-cd/#deploy) for the component. + Alternatively, select the **Use Public GitHub Repository** option and paste the [Choreo samples repository](https://github.com/wso2/choreo-samples) URL in the **Provide Repository URL** field to connect to it without requiring authorization from the [Choreo Apps](https://github.com/marketplace/choreo-apps) GitHub application. However, authorizing the repository with the [Choreo GitHub App](https://github.com/marketplace/choreo-apps) is necessary if you want to enable [**Auto Deploy**](https://wso2.com/choreo/docs/choreo-concepts/ci-cd/#deploy) for the component. !!! note The **Choreo GitHub App** requires the following permissions: @@ -47,43 +35,44 @@ You can develop tests in a language of your choice and execute them within the C You can [revoke access](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/reviewing-your-authorized-integrations#reviewing-your-authorized-github-apps) if you do not want Choreo to have access to your GitHub account. However, write access is exclusively utilized for sending pull requests to a user repository. Choreo will not directly push any changes to a repository. -7. Under **Connect Your Repository**, enter the following information: +7. Under **Connect a Git Repository**, enter the following information: | **Field** | **Value** | |------------------------|--------------------| | **Organization** | Your GitHub account| | **GitHub Repository** | choreo-samples | | **Branch** | **`main`** | + | **Component Directory**| `/test-runner-go` | + + You also can select a different language: -6. Under **Buildpack**, select a buildpack based on the language of your choice. -7. Based on the buildpack you chose, go to the relevant tab below and enter the respective values for the **Project directory** and **Language version** fields: === "Go" | Field | Value | | -------------------- | --------------- | - | Go Project Directory | /test-runner-go | + | Component Directory | /test-runner-go | | Language Version | 1.x | === "JavaScript" | Field | Value | | ----------------- | ----------------------- | - | Project Directory | /test-runner-javascript | + | Component Directory | /test-runner-javascript | | Language Version | 18.x.x | === "Python" | Field | Value | | ----------------- | ----------------------- | - | Project Directory | /test-runner-python | + | Component Directory | /test-runner-python | | Language Version | 3.10.x | === "Java" | Field | Value | | ----------------- | ----------------------- | - | Project Directory | /test-runner-java | + | Component Directory | /test-runner-java | | Language Version | 17 | === "Dockerfile" @@ -94,8 +83,23 @@ You can develop tests in a language of your choice and execute them within the C | Field | Value | | ----------------- | ----------------------- | - | Postman Directory | /postman-collection-dir | + | Component Directory | /postman-collection-dir | + + +6. Under **Buildpack**, select a buildpack based on the language of your choice. +7. Based on the buildpack you chose, go to the relevant tab above and enter the respective values for the **Language version** field + +4. Enter a display name, unique name, and description for the test runner component. For this guide, enter the following values: + !!! info + In the **Component Name** field, you must specify a name to uniquely identify the component in various contexts. The value is editable only at the time you create the component. You cannot change the name after you create the component. + + | Field | Value | + | -------------------------|-------------------------------- | + | Component Display Name | `Go Test Runner` | + | Component Name | `go-test-runner` | + | Description | `Test Runner implemented in Go` | + 8. Click **Create**. You have successfully created a Test Runner component using a buildpack of your choice. Now let's build and run the tests. diff --git a/en/docs/testing/test-graphql-endpoints-via-the-graphql-console.md b/en/developer-docs/docs/testing/test-graphql-endpoints-via-the-graphql-console.md similarity index 100% rename from en/docs/testing/test-graphql-endpoints-via-the-graphql-console.md rename to en/developer-docs/docs/testing/test-graphql-endpoints-via-the-graphql-console.md diff --git a/en/developer-docs/docs/testing/test-rest-endpoints-via-the-openapi-console.md b/en/developer-docs/docs/testing/test-rest-endpoints-via-the-openapi-console.md new file mode 100644 index 000000000..231d3b6e5 --- /dev/null +++ b/en/developer-docs/docs/testing/test-rest-endpoints-via-the-openapi-console.md @@ -0,0 +1,31 @@ +# Test REST Endpoints via the OpenAPI Console + +Choreo offers an integrated OpenAPI Console to test REST endpoints for the Service components you create and deploy. Since Choreo secures REST APIs with OAuth 2.0 authentication, the OpenAPI Console generates test keys to help you test your APIs. + +Follow these steps to test a REST endpoint using the OpenAPI Console: + +1. Go to the [Choreo Console](https://console.choreo.dev/) and log in. +2. In the **Component Listing** pane, click on the component you want to test. +3. Click **Test** in the left navigation menu, then select **Console**. This will open the **OpenAPI Console** pane. +4. In the **OpenAPI Console** pane, select the desired environment from the drop-down menu. +5. Choose the endpoint you want to test from the **Endpoint** list. + + !!! note + - The **Network Visibility** of an endpoint is configured in the **component.yaml** file. You can set it to **Public**, **Organization**, or **Project**. + - If the **Network Visibility** is set to **Public**, skip to step 7. + - If the **Network Visibility** is set to **Organization**, the endpoint is not publicly accessible. However, Choreo allows you to generate a temporary test URL for testing purposes. This URL is publicly accessible (secured with OAuth 2.0) and remains active for 15 minutes. To generate the temporary URL, proceed to step 6. + +6. Generate a temporary test URL (if applicable): + If the **Network Visibility** is set to **Organization**, click **Generate URL** to create a temporary test URL. This URL will be active for 15 minutes. If the visibility is not set to **Organization**, skip this step. + + !!! note + The temporary test URL is valid for **15 minutes only** and will expire afterward. You can manually deactivate it by clicking the **Deactivate URL** button. + + ![OpenAPI Console](../assets/img/testing/openapi-console-org.png){.cInlineImage-full} + +7. Expand the resource you want to test. +8. Click the **Try it out** button to enable testing. +9. Provide values for any parameters, if applicable. +10. Click **Execute**. The response will be displayed under the **Responses** section. + + ![OpenAPI Console](../assets/img/testing/openapi-console.png){.cInlineImage-full} diff --git a/en/developer-docs/docs/testing/test-websocket-endpoints-via-the-websocket-console.md b/en/developer-docs/docs/testing/test-websocket-endpoints-via-the-websocket-console.md new file mode 100644 index 000000000..8ff4f815d --- /dev/null +++ b/en/developer-docs/docs/testing/test-websocket-endpoints-via-the-websocket-console.md @@ -0,0 +1,32 @@ +# Test Websocket Endpoints via the Websocket Console + +Choreo provides an integrated WebSocket Console to test publicly exposed WebSocket endpoints of Service components you create and deploy. The WebSocket Console allows you to connect to your service and interactively exchange messages. By default, Choreo secures WebSocket APIs with OAuth 2.0, and the console automatically generates test keys for authenticated API testing. + +Follow these steps to test a WebSocket endpoint using the WebSocket Console: + +1. Go to the [Choreo Console](https://console.choreo.dev/) and log in. +2. In the **Component Listing** pane, click on the component you want to test. +3. Click **Test** in the left navigation menu, then select **Console**. This opens the **WebSocket Console** pane. +4. In the **WebSocket Console** pane, select the desired environment from the drop-down list. +5. Choose the endpoint you want to test from the **Endpoint** list. + + !!! note + - The **Network Visibility** of an endpoint is configured in the **endpoints.yaml** file. You can set it to **Public**, **Organization**, or **Project**. + - If the **Network Visibility** is set to **Public**, proceed to step 7. + - If the **Network Visibility** is set to **Organization**, the endpoint won't be accessible outside the organization. For testing, Choreo allows you to generate a temporary URL that remains active for 15 minutes. Follow step 6 to generate the URL. + +6. Generate a temporary URL (if applicable): + If the **Network Visibility** is set to **Organization**, click **Generate URL** to create a temporary test URL valid for 15 minutes. Otherwise, skip this step. + + !!! note + The temporary test URL is valid for **15 minutes** and will expire afterward. To manually deactivate it, click **Deactivate URL**. + + ![WebSocket Console](../assets/img/testing/websocket-console.png){.cInlineImage-full} + +7. Expand the channel you want to test. +8. Click **Connect** to establish a connection. The connection status will be displayed in the output logs. +9. Send and receive messages: + Interact with the deployed service by sending and receiving messages. + + !!! note + The maximum connection duration is **15 minutes**. After that, the connection terminates. To reconnect, click **Connect** again. diff --git a/en/developer-docs/docs/tutorials/consume-an-api-hosted-in-choreo.md b/en/developer-docs/docs/tutorials/consume-an-api-hosted-in-choreo.md new file mode 100644 index 000000000..77c06f328 --- /dev/null +++ b/en/developer-docs/docs/tutorials/consume-an-api-hosted-in-choreo.md @@ -0,0 +1,170 @@ +# Consume an OAuth2 Secured Service + +Choreo is a platform that allows you to create, deploy, and consume services seamlessly. The Choreo Developer Portal simplifies the process of discovering and using APIs for developers. + +This guide is designed for application developers (internal or external to your organization) who want to consume APIs published in the Developer Portal to build their applications. You will learn how to: + +- Discover APIs +- Create an application and generate credentials +- Subscribe to an API +- Consume a published REST API via a web application + +## Prerequisites + +If you don’t already have a published service to consume, follow the [Develop a Service](../develop-components/develop-services/develop-a-service.md) documentation to publish and deploy a sample REST API. + +## Discover APIs + +In the Choreo Developer Portal, developers can search for APIs by name. APIs and services created and published through the Choreo Console are visible in the Developer Portal based on their visibility settings: + +- **Public**: The API is visible to everyone in the Developer Portal. +- **Private**: The API is visible only to users who sign in to the Developer Portal. +- **Restricted**: The API is visible only to users with specific roles. This allows for fine-grained access control. + +To learn more about API visibility, see [Control API Visibility](../api-management/control-api-visibility.md). + +The Developer Portal lists APIs by their major version. + +![Developer Portal APIs](../assets/img/consume/developer-portal-apis.png) + +The API overview page displays subscribed versions of the API along with subscription details such as the application name and creation date. + +![API overview](../assets/img/consume/api-overview.png) + +!!! tip + To use an API, it’s recommended to use the latest version. Copy the **Endpoint(s)** value from the API overview page and use it in your client application. This ensures your application always invokes the latest API version. + +## Create an application + +{% include "../consuming-services/create-an-application.md" %} + +## Subscribe to an API + +{% include "../consuming-services/create-a-subscription.md" %} + +## Consume the API via your web application + +To securely invoke the API/service, you need to use your Identity Provider (IdP). Follow these steps: + +1. Create a web application in Choreo. +2. Create an OAuth application in the IdP. +3. Configure the web application to authenticate API/service invocations using the IdP. +4. Deploy the web application. + +For this guide, you’ll use: +- **WSO2 Asgardeo** as the IdP. +- **[choreo-samples/reading-list-app/reading-list-front-end](https://github.com/wso2/choreo-samples/tree/main/reading-list-app/reading-list-front-end)** as the web application. This is a React SPA that uses Axios to invoke the service. It is configured to work with the **[choreo-samples/reading-list-app/reading-list-service](https://github.com/wso2/choreo-samples/tree/main/reading-list-app/reading-list-service)**. You can modify this web application to work with your service or deploy the sample service in Choreo. + +### Step 1: Create a web application component + +!!! info + You can use your own web application instead of the sample. For this guide, you’ll use the [choreo-samples/reading-list-app/reading-list-front-end](https://github.com/wso2/choreo-samples/tree/main/reading-list-app/reading-list-front-end). + +To host the front-end application in Choreo, create a web application component: + +1. In the Choreo Console, select the project for the reading list application from the project list in the header. +2. Click **Create** under the **Component Listing** section. +3. On the **Web Application** card, click **Create**. +4. Enter the following details: + + | **Field** | **Value** | + |-----------------|-------------------------| + | **Name** | `Reading List Web App` | + | **Description** | `Frontend application for the reading list service` | + +5. Click **Next**. +6. Click **Authorize with GitHub** to connect Choreo to your GitHub account. +7. In the **Connect Repository** pane, enter the following: + + | **Field** | **Value** | + |-----------------------|-----------------------------------------| + | **GitHub Account** | Your account | + | **GitHub Repository** | **`choreo-samples`** | + | **Branch** | **`main`** | + | **Buildpack** | **React** (since it’s a React app built with Vite) | + | **Build Context Path**| **`reading-list-app/reading-list-front-end`** | + | **Build Command** | **`npm install && npm run build`** | + | **Build Output** | **`dist`** | + | **Node Version** | **`18`** | + +8. Click **Create**. This initializes the service with the GitHub repository and takes you to the **Overview** page. + +### Step 2: Create an OAuth application in the IdP + +To invoke the API/service, you need an access token. Create an OAuth application in the IdP (for example, Asgardeo) with the following settings: + +- **Allowed grant types**: Code +- **Public client**: Enable this option. +- **Authorized redirect URLs**: Add the web app URL. +- **Allowed origins**: Add the same URLs as authorized redirect URLs. +- **Access Token**: Set to JWT. + +Choreo uses Asgardeo as the default IdP. When you create an application in the Choreo Developer Portal, it automatically creates a corresponding application in Asgardeo. Follow these steps to configure the Asgardeo OAuth application: + +1. Sign in to [Asgardeo](https://console.asgardeo.io/) using the same credentials as Choreo. +2. Ensure you’re in the same organization used in the Choreo Developer Portal. +3. In the Asgardeo Console, click **Applications** in the left navigation. You’ll see the **readingListApp** created by Choreo. +4. Click the edit icon to edit the application. +5. Go to the **Protocol** tab and make the following changes: + 1. Under **Allowed grant types**, select **Code**. + 2. Select the **Public client** checkbox. + 3. In **Authorized redirect URLs**, enter the web app URL and click **+** to add it. + 4. In **Allowed origins**, add the same URLs. + 5. Under **Access Token**, select **JWT** as the token type. + 6. Click **Update**. + +### Step 3: Configure the web application to connect to the IdP and invoke the service + +Update the web app configurations to invoke the **Reading List Service** REST API. These configurations are environment-specific. For this guide, we’ll configure the development environment. + +!!! note + The web app reads environment-specific configurations from the `window` object at runtime via the `config.js` file. You’ll mount this file for the development environment. Repeat this process for other environments as needed. + +To configure the front-end application: + +1. On the web application component page, click **DevOps** in the left menu, then click **Configs and Secrets**. +2. Click **+ Create**. +3. Select the following options and click **Next**: + + | **Field** | **Value** | + |-----------------------|-----------------------------------------| + | **Config Type** | **Config Map** | + | **Mount Type** | **File Mount** | + +4. Specify the following values: + + | **Field** | **Value** | + |-----------------------|-----------------------------------------| + | **Config Name** | **Web App Config** | + | **Mount Path** | **/usr/share/nginx/html/config.js** | + +5. Copy the following JSON configuration into the text area. Replace the placeholders with the values from earlier steps: + + ```javascript + window.config = { + redirectUrl: "", + asgardeoClientId: "", + asgardeoBaseUrl: "https://api.asgardeo.io/t/", + choreoApiUrl: "" + }; + ``` + + | **Field** | **Description** | + |-----------------------|-----------------------------------------------| + | **redirectUrl** | The web app URL you copied earlier. | + | **asgardeoClientId** | The **Client ID** from the Asgardeo application. | + | **asgardeoBaseUrl** | The IdP API URL with your organization name (e.g., `https://api.asgardeo.io/t/`). | + | **choreoApiUrl** | The **Reading List Service** URL from the endpoint table in the overview page. | + +6. Click **Create**. + +### Step 4: Deploy the web application + +To deploy the web application: + +1. In the left menu, click **Deploy**. +2. In the **Build Area** card, click **Deploy Manually**. Deployment may take a few minutes. +3. Once deployed, copy the **Web App URL** from the development environment card. +4. Navigate to the web app URL to verify it’s successfully hosted. + +That’s it! You can now use a user from your IdP to sign in and invoke the service through your web application. diff --git a/en/developer-docs/docs/tutorials/expose-a-service-as-a-managed-api.md b/en/developer-docs/docs/tutorials/expose-a-service-as-a-managed-api.md new file mode 100644 index 000000000..9d0ecbf4b --- /dev/null +++ b/en/developer-docs/docs/tutorials/expose-a-service-as-a-managed-api.md @@ -0,0 +1,115 @@ +# Expose a Service as a Managed API + +Choreo simplifies securely exposing existing services as managed APIs. It also allows you to manage all aspects of an API's lifecycle, security, throttling, and governance, so you can focus on service development. + +In this tutorial, you will use Choreo to expose a service as an API proxy and publish it to the Choreo Developer Portal for application developers to consume. + +## Prerequisites + +- If you're signing in to the Choreo Console for the first time, create an organization: + 1. Go to [https://console.choreo.dev/](https://console.choreo.dev/) and sign in using your preferred method. + 2. Enter a unique organization name. For example, `Stark Industries`. + 3. Read and accept the privacy policy and terms of use. + 4. Click **Create**. + + This creates the organization and opens the **Project Home** page of the default project created for you. + +## Step 1: Create an API proxy + +To create an API proxy, you can either upload an OpenAPI specification or provide an OpenAPI specification URL. In this tutorial, you will use a sample OpenAPI specification URL. + +1. Go to [https://console.choreo.dev/](https://console.choreo.dev/) and sign in. This opens the project home page. +2. If you already have one or more components in your project, click **+ Create** under **Component Listing**. Otherwise, proceed to the next step. +3. Click the **API Proxy** card. +4. In the **Create an API Proxy** pane, click **Try with sample URL**. +5. Click **Next**. +6. Update the populated API proxy details with the following values: + + !!! info + The **Name** field must be unique and cannot be changed after creation. + + | **Field** | **Value** | + |-----------------|---------------------------------------------| + | **Display Name**| `Swagger Petstore` | + | **Name** | `swagger-petstore` | + | **Context** | `api/v3` | + | **Version** | `1.0` | + | **Target** | `https://petstore3.swagger.io/api/v3` | + | **Access Mode** | **External**: API is publicly accessible | + +7. Click **Create**. This creates the component and takes you to the **Overview** page of the component. + +To see the resources of the API proxy, go to the left navigation menu, click **Develop**, and then click **Resources**. + +## Step 2: Deploy the API proxy + +1. In the left navigation menu, click **Deploy**. +2. In the **Build Area** card, click **Configure & Deploy**. This opens the **Configure & Deploy** pane. +3. Select **External** to make the API publicly accessible, and then click **Deploy**. + + Once the deployment is complete, the **Development** card indicates the **Deployment Status** as **Active**. + +Now you are ready to test the API proxy. + +## Step 3: Test the API proxy + +You can test the API proxy in the development environment before promoting it to production. Choreo provides the following options to test your API proxy: +- OpenAPI Console +- cURL + +In this guide, you will use the OpenAPI Console. + +1. In the left navigation menu, click **Test** and then click **OpenAPI Console**. + + !!! tip + Since the API proxy is secured when deployed, you will need a key to invoke it. Choreo automatically generates a key when you navigate to the **OpenAPI Console** pane. + +2. In the **OpenAPI Console** pane, select **Development** from the environment drop-down list. +3. Expand the `GET /pet/findByStatus` method and click **Try it Out** to test it. +4. Select **available** as the status and click **Execute**. You will see a response similar to the following: + + ![API proxy response](../assets/img/tutorials/api-proxy-response.png) + + This indicates that your API proxy is working as expected. + +## Step 4: Promote the API proxy to production + +Once you verify that the API proxy is working as expected in the development environment, you can promote it to production. + +1. In the left navigation menu, click **Deploy**. +2. In the **Development** card, click **Promote**. +3. In the **Configure & Deploy** pane, click **Next**. + + !!! tip + If you want to specify a different endpoint for your production environment, you can make the change in the **Configure & Deploy** pane. + + The **Production** card indicates the **Deployment Status** as **Active** when the API proxy is successfully deployed to production. + + If you want to verify that the API proxy is working as expected in production, you can test the API in the production environment. + +Now that your API is deployed in both development and production environments and can be invoked, the next step is to publish it so that consumers can discover and subscribe to it. + +## Step 5: Publish the API proxy + +1. In the left navigation menu, click **Manage** and then click **Lifecycle**. This opens the **Lifecycle** page, where you can see the different lifecycle stages of the API. The current lifecycle stage is **Created**. +2. Click **Publish**. +3. In the **Publish API** dialog, click **Confirm** to proceed with publishing the API with the specified display name. If you want to change the display name, make the necessary changes and then click **Confirm**. This changes the API lifecycle state to **Published**. + +You can observe that the API lifecycle stage has changed to **Published**. Now the API is available for consumption. API consumers can consume the API via the Choreo Developer Portal. + +## Step 6: Invoke the API + +To generate credentials for the published API and invoke it via the Developer Portal, follow these steps: + +1. In the **Lifecycle Management** pane, click **Go to DevPortal**. This takes you to the Petstore API published to the Choreo Developer Portal. +2. Generate credentials: + 1. In the Developer Portal left navigation menu, click **Production** under **Credentials**. + 2. Click **Generate Credentials**. Choreo generates new tokens and populates the **Consumer Key** and **Consumer Secret** fields. +3. Invoke the API: + 1. In the Developer Portal left navigation menu, click **Try Out**. + 2. In the **Endpoint** list, select **Development** as the environment to try out the API. + 3. Click **Get Test Key**. This generates an access token. + 4. Expand the `GET /pet/findByStatus` operation and click **Try it out**. + 5. Select **available** as the status and click **Execute**. + +Now you have successfully created, deployed, tested, and published an API proxy using Choreo. diff --git a/en/developer-docs/docs/tutorials/secure-an-api-with-role-based-access-control.md b/en/developer-docs/docs/tutorials/secure-an-api-with-role-based-access-control.md new file mode 100644 index 000000000..1162bbb89 --- /dev/null +++ b/en/developer-docs/docs/tutorials/secure-an-api-with-role-based-access-control.md @@ -0,0 +1,150 @@ +# Secure an API with Role-Based Access Control + +Role-based access control (RBAC) is a flexible and scalable approach to manage access to API resources. In this approach, each user or group is assigned a specific role that determines the permissions granted to perform operations on an API resource. + +This tutorial explains how to implement RBAC using Choreo and Asgardeo. It includes a real-world scenario with instructions to create and publish an API proxy component in Choreo and apply role-based access control. + +## Scenario + +An organization needs to implement a user management service to keep track of users. The service needs to perform the following operations: + +- List existing users +- List a specific user +- Create new users +- Delete a user + +There are two types of users in the organization: + +- **Human resource manager (HR manager)**: Can perform all operations (list users, list a user, create users, and delete a user). +- **Human resource officer (HR officer)**: Can only list existing users and list a specific user. + +## Implement role-based access control with Choreo and Asgardeo + +Let’s take a look at the steps to implement the scenario described above using Choreo and Asgardeo. + +### Prerequisites + +- If you're signing in to the Choreo Console for the first time, create an organization: + 1. Go to [https://console.choreo.dev/](https://console.choreo.dev/) and sign in using your preferred method. + 2. Enter a unique organization name. For example, `Stark Industries`. + 3. Read and accept the privacy policy and terms of use. + 4. Click **Create**. + +This creates the organization and opens the home page of the default project created for you. + +### Step 1: Create an API proxy component and deploy it + +1. Go to [https://console.choreo.dev/](https://console.choreo.dev/cloud-native-app-developer) and sign in. This opens the project home page. +2. To create an API proxy component, follow the instructions in [Develop an API Proxy: Step 1](../develop-components/develop-an-api-proxy.md#step-1-create-an-api-proxy). This opens the **Resources** pane, where you can define resources for the API proxy. +3. In the **Resources** pane, add the following resources: + - **GET** `/users` + - **GET** `/users/{userID}` + - **POST** `/users` + - **DELETE** `/users/{userID}` +4. Remove the five default resources that start with `/*` by clicking the delete icon corresponding to each resource. +5. Click **Save**. The API resources will look like this: + + ![API resources](../assets/img/tutorials/role-based-auth/api-resources.png) + +6. In the left navigation menu, click **Deploy**. +7. Go to the **Build Area** card and click **Configure & Deploy**. +8. In the **Configure API Access Mode** pane, select **External** to make the API publicly accessible. +9. Click **Deploy**. + +### Step 2: Apply permissions to resources and publish the API + +1. On the **Deploy** page, go to the **Build Area** card and click **Security Settings**. +2. In the **Security Settings** pane, go to the **Permissions List** section and click **+ Add Permission(Scope)**. +3. Add the following permission values: + - `get_user_list` + - `get_user` + - `create_user` + - `delete_user` +4. In the **Permissions** section, assign permissions to resources as follows: + + | **Resource** | **Permission** | + |--------------------------|----------------| + | **GET /users** | `get_user_list`| + | **GET /users/{userID}** | `get_user` | + | **POST /users** | `create_user` | + | **DELETE /users/{userID}**| `delete_user` | + +5. Click **Apply**. +6. Redeploy the API to apply the latest permissions: + 1. Go to the **Build Area** card and click **Configure & Deploy**. + 2. Select **External** as the access mode and click **Deploy**. +7. Promote the API to production: + 1. In the left navigation menu, click **Deploy**. + 2. Go to the **Development** card and click **Promote**. + 3. In the **Configure & Deploy** pane, click **Next** to promote the API to production. +8. Publish the API: + 1. In the left navigation menu, click **Manage** and then click **Lifecycle**. + 2. In the **Lifecycle Management** pane, click **Publish**. This changes the API status to **Published**. + +Now, application developers can discover the API, subscribe to it, and invoke it. + +### Step 3: Subscribe to the published API + +1. Go to the [API Developer Portal](https://devportal.choreo.dev/) and click **Applications** on the top menu. +2. Click **+Create**. +3. Enter `User Management App` as the **Application Name** and click **Create**. +4. In the Developer Portal left navigation menu, click **Production** under **Credentials**. +5. Expand **Advanced Configurations** and: + 1. Select **Code** as the grant type. + 2. Enter the hosted URL of the application as the **Callback URL**. + 3. Click **Generate Credentials**. +6. Subscribe to the API: + 1. In the Developer Portal left navigation menu, click **Subscriptions**. + 2. In the **Subscription Management** pane, click **Add APIs**. + 3. In the **Add APIs** list, go to the API you created and click **Add**. + +### Step 4: Define roles and assign them to groups + +1. In the Developer Portal left navigation menu, click **Production** under **Credentials**. +2. In the **Permissions** section, click **Manage Permissions**. This takes you to the **Roles** tab of the `User Management App` application in Asgardeo. +3. Add the following roles: + - **admin**: Assign permissions `get_user_list`, `get_user`, `create_user`, and `delete_user`. + - **user**: Assign permissions `get_user_list` and `get_user`. +4. Create groups and assign roles: + - **HR-Manager**: Assign the **admin** role. + - **HR-Officer**: Assign the **user** role. + +### Step 5: Define users and assign them to groups + +1. Define two users: `Cameron` and `Alex`. For instructions, see [Manage Users](https://wso2.com/asgardeo/docs/guides/users/manage-customers/#onboard-a-user) in the Asgardeo documentation. +2. Assign `Cameron` to the **HR-Manager** group and `Alex` to the **HR-Officer** group. For instructions, see [Assign Groups](https://wso2.com/asgardeo/docs/guides/users/manage-customers/#assign-groups). + +### Step 6: Obtain an access token and try out the API + +1. Construct the authorization URL as follows: + + ``` + ?response_type=code&client_id=&redirect_uri=&scope= + ``` + + - Replace `` with the **Authorize Endpoint** URL. + - Replace `` with the **Callback URL**. + - Replace `` with the applicable permissions (e.g., `get_user_list get_user` for `Alex`). + - Replace `` with the **Consumer Key**. + +2. Open the constructed URL in a web browser and sign in with `Alex`'s credentials. Click **Allow** to approve the consent. +3. Copy the code from the callback URL and use it to replace `` in the following cURL command: + + ``` + curl -d "grant_type=authorization_code&code=&redirect_uri=" -H "Authorization: Basic " + ``` + + - Replace `` with the **Token Endpoint** URL. + - Replace `` with the **Callback URL**. + - Replace `` with the Base64-encoded value of `clientId:clientSecret`. + +4. Extract the access token from the response. +5. Go to the [API Developer Portal](https://devportal.choreo.dev/) and try out the API using the access token. Observe that `Alex` can only access the following resources: + - **GET /users** + - **GET /users/{userID}** + + Attempting to access other resources will result in a scope validation error. + + Similarly, if you use `Cameron`'s credentials, you can access all four resources because the token includes all required permissions. + +Now you have gained hands-on experience in implementing role-based access control with Choreo and Asgardeo. diff --git a/en/developer-docs/docs/what-is-choreo.md b/en/developer-docs/docs/what-is-choreo.md new file mode 100644 index 000000000..a2b88445f --- /dev/null +++ b/en/developer-docs/docs/what-is-choreo.md @@ -0,0 +1,39 @@ +# What is Choreo? + +Choreo is an internal developer platform designed to redefine how you create digital experiences. It empowers you to seamlessly design, develop, deploy, and govern cloud-native applications, unlocking innovation while reducing time-to-market. Just add developers to Choreo while maintaining operational control. + +## Key capabilities of Choreo + +### Design for security, governance, and efficiency +- **Domain-Driven Design**: Organize enterprise systems into domains, exposing managed APIs, events, and data through projects. Each project consists of components representing units of deployment. +- **Application Security Design**: Leverage [cell-based architecture](https://github.com/wso2/reference-architecture/blob/master/reference-architecture-cell-based.md), where projects become governable units from development to deployment, ensuring managed access via APIs, events, and data. + +### Efficient and effective development +- **Code in Any Language**: Develop applications in your team's preferred programming language, harnessing existing skill sets to build powerful polyglot APIs, services, events, tasks, and more. +- **Native Support for VS Code**: Seamlessly collaborate and manage code using VS Code in a feature-rich, visually-enhanced development environment. +- **Git Repository Integration**: Effortlessly connect to Git-based platforms like GitHub, Bitbucket, or GitLab to develop components by linking an existing repository. + +### Seamless deployment +- **CI/CD**: Eliminate manual builds and unreliable deployments with Choreo's industry-standard CI/CD tooling, providing complete control and flexibility. +- **Multi-Cloud Kubernetes**: Easily deliver cloud-native applications across Azure, AWS, GCP, or your Kubernetes clusters. +- **Configuration Management**: Centralize configuration parameters, sensitive credentials, and secrets across deployment environments via an intuitive interface. + +### Effortless management of APIs, integrations, microservices, and web applications +- **Enable Security**: Empower security teams to manage data flows, ensuring seamless control over sensitive information like access credentials. +- **Scale Up or Down**: Kubernetes handles scaling automatically, optimizing costs by scaling services based on demand. +- **Ensure Reliability**: DevOps and SRE teams can easily manage deployed components with built-in insights and observability. + +### Reusable digital assets +- **Control Visibility and Sharing**: Publish your digital assets to a shared marketplace for consumption by internal or external stakeholders, managed by role-based access control. +- **Internal Marketplace**: Choreo's secure internal marketplace fosters transparency and efficiency with granular access control for publishers and consumers. + +### Comprehensive observability +- **Anomaly Detection**: Stay ahead of issues with prompt notifications, ensuring balanced scaling and immediate action during unexpected mishaps. +- **Troubleshoot and Debug**: Quickly pinpoint and address root causes using detailed logs and data aligned in the same timeline, down to the machine-level details. + +### Robust governance +- **DORA Metrics**: Monitor your DevOps efficiency with Choreo DORA metrics, experiencing rapid improvements in time from deployment to production safely and robustly. +- **Engineering Insights**: Gain visibility into engineering insights and advanced data analytics to make data-driven decisions, optimize processes, and improve efficiency. +- **API Analytics**: Understand API performance and adoption patterns to identify and resolve operational bottlenecks. + +Choreo is your all-in-one platform for building, deploying, and managing cloud-native applications with ease, security, and efficiency. diff --git a/en/developer-docs/mkdocs.yml b/en/developer-docs/mkdocs.yml new file mode 100644 index 000000000..f56a4bf03 --- /dev/null +++ b/en/developer-docs/mkdocs.yml @@ -0,0 +1,460 @@ +# Copyright (c) 2021, WSO2 Inc. (http://www.wso2.org) All Rights Reserved. +# +# WSO2 Inc. licenses this file to you under the Apache License, +# Version 2.0 (the "License"); you may not use this file except +# in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, +# software distributed under the License is distributed on an +# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +# KIND, either express or implied. See the License for the +# specific language governing permissions and limitations +# under the License. + +# Project information +site_name: "" +site_description: Choreo Learning Portal +site_author: WSO2 +site_url: https://wso2.com/choreo/docs +site_dir: site/developer + +# Repository +repo_name: wso2/docs-choreo-dev +repo_url: https://github.com/wso2/docs-choreo-dev/ +edit_uri: https://github.com/wso2/docs-choreo-dev/edit/dev/en/docs/ +dev_addr: localhost:8000 + +# Copyright +copyright: ©2023 WSO2 LLC. + +# Configuration +theme: + name: material + custom_dir: ../theme/material + logo: assets/images/logo.png + font: + text: Montserrat + favicon: assets/images/favicon.png + features: + - navigation.expand + - navigation.path + - navigation.top + - content.code.copy + - content.action.edit + - content.action.view + - version.selector + language: "en" + palette: + # Palette toggle for automatic mode + - media: "(prefers-color-scheme)" + toggle: + icon: material/brightness-auto + name: Switch to dark mode + + # Palette toggle for light mode + - media: "(prefers-color-scheme: light)" + scheme: default + toggle: + icon: material/brightness-7 + name: Switch to system preference + + # Palette toggle for dark mode + - media: "(prefers-color-scheme: dark)" + scheme: slate + toggle: + icon: material/brightness-4 + name: Switch to light mode + icon: + logo: logo +#Breaks build if there's a warning +strict: false +# Navigation +nav: + - Home: index.md + - Introduction: + - What is Choreo?: what-is-choreo.md + - Quick Start Guides: + - Deploy Your First Service: quick-start-guides/deploy-your-first-service.md + - Deploy Your First Static Web Application: quick-start-guides/deploy-your-first-static-web-application.md + - Deploy a Web Application that Consumes a Backend Service: quick-start-guides/deploy-a-web-application-that-consumes-a-backend-service.md + - Choreo Samples: + - Explore the Samples Collection: + - Samples Overview: choreo-samples/samples-overview.md + - Quick Deploy a Sample: choreo-samples/quick-deploy-a-sample.md + - Explore the Demo Organization: choreo-samples/explore-the-demo-organization.md + - Tutorials: + - Expose a Service as a Managed API: tutorials/expose-a-service-as-a-managed-api.md + - Secure an API with Role-Based Access Control: tutorials/secure-an-api-with-role-based-access-control.md + - Consume an API hosted in Choreo: tutorials/consume-an-api-hosted-in-choreo.md + - Choreo Concepts: + - Resource Hierarchy: choreo-concepts/resource-hierarchy.md + - Organization: choreo-concepts/organization.md + - Project: choreo-concepts/project.md + - Component: choreo-concepts/component.md + - Endpoint: choreo-concepts/endpoint.md + - CI/CD: choreo-concepts/ci-cd.md + - Deployment Tracks: choreo-concepts/deployment-tracks.md + - Connections: choreo-concepts/connections.md + - Data Planes: choreo-concepts/data-planes.md + - Environments: choreo-concepts/environments.md + - Choreo Marketplace: choreo-concepts/choreo-marketplace.md + - Develop Components: + - Develop Services: + - Service Component Overview: develop-components/develop-services/service-component-overview.md + - Develop a Service: develop-components/develop-services/develop-a-service.md + - Develop a service with Docker: develop-components/develop-services/develop-a-service-with-docker.md + - Develop a Ballerina Service: develop-components/develop-services/develop-a-ballerina-service.md + - Expose a gRPC Endpoint via a Service: develop-components/develop-services/expose-a-grpc-endpoint-via-a-service.md + - Expose a TCP Server via a Service: develop-components/develop-services/expose-a-tcp-server-via-a-service.md + - Expose a UDP Server via a Service: develop-components/develop-services/expose-a-udp-server-via-a-service.md + - Expose a Ballerina GraphQL Endpoint via a Service: develop-components/develop-services/expose-a-ballerina-graphql-endpoint-via-a-service.md + - Expose a Prism-Based Mock Server Using an OpenAPI Specification: develop-components/develop-services/expose-a-prism-based-mock-server-using-an-openapi-specification.md + - Expose a WebSocket Endpoint via a Service: develop-components/develop-services/expose-a-websocket-endpoint-via-a-service.md + - Develop an API Proxy: + - Develop an API Proxy from Scratch : develop-components/develop-proxy/develop-an-api-proxy-from-scratch.md + - Develop an API Proxy from Git Repository Source : develop-components/develop-proxy/develop-an-api-proxy-from-a-github-repository-source.md + - Develop Web Applications: + - Build and Deploy a Single-Page Web Application: develop-components/develop-web-applications/build-and-deploy-a-single-page-web-application.md + - Develop Web Applications Locally with Choreo’s Managed Authentication: develop-components/develop-web-applications/develop-web-applications-locally-with-managed-authentication.md + - Develop a Webhook: develop-components/develop-a-webhook.md + - Develop an External Consumer: develop-components/develop-an-external-consumer.md + - Develop Integrations: + - Develop an Integration with Integration Studio: develop-components/develop-integrations/develop-an-integration-with-integration-studio.md + - Develop an Event Handler: develop-components/develop-integrations/develop-an-event-handler.md + - Develop a Scheduled Task: develop-components/develop-integrations/develop-a-scheduled-task.md + - Develop a Manual Task: develop-components/develop-integrations/develop-a-manual-task.md + - Work with the Micro Integrator Runtime: + - Get Started with the Micro Integrator Runtime: develop-components/work-with-the-micro-integrator-runtime-in-choreo.md + - Manage the Micro Integrator Runtime Version in Your Integration Project: develop-components/manage-the-micro-integrator-runtime-version-in-your-integration-project.md + - Develop Components With Git: develop-components/develop-components-with-git.md + - Bring Your Own Image: develop-components/bring-your-own-image.md + - Deploy an Application with Buildpacks: develop-components/deploy-an-application-with-buildpacks.md + - Deploy a Containerized Application: develop-components/deploy-a-containerized-application.md + - Integrate Unit Tests into the Build Pipeline: develop-components/integrate-unit-tests-into-the-build-pipeline.md + - Share and Reuse Components: + - Create a Connection: develop-components/sharing-and-reusing/create-a-connection.md + - Use a Connection in Your Service: develop-components/sharing-and-reusing/use-a-connection-in-your-service.md + - Use a Connection in Your Web Application: develop-components/sharing-and-reusing/use-a-connection-in-your-web-application.md + - Use a Database Connection in Your Component: develop-components/sharing-and-reusing/use-a-database-connection-in-your-component.md + - Manage Deployment Tracks for Choreo Components: develop-components/manage-deployment-tracks-for-choreo-components.md + - Configure Endpoints: develop-components/configure-endpoints.md + - Manage Component Source Configurations: develop-components/manage-component-source-configurations.md + - Submit and Manage Workflow Approval Requests: develop-components/submit-and-manage-workflow-approval-requests.md + - Develop Components Using VS Code: develop-components/develop-components-using-vs-code.md + - Integrate and Manage External Services: + - Integrate and Manage Third-Party Services: integrate-and-manage-external-services/integrate-and-manage-third-party-services.md + - Integrate and Manage Generative AI Services: integrate-and-manage-external-services/integrate-and-manage-gen-ai-services.md + - Choreo-Managed Databases and Caches: + - Overview: manage-databases-and-caches/choreo-managed-databases-and-caches.md + - PostgreSQL: manage-databases-and-caches/choreo-managed-postgresql-databases.md + - MySQL: manage-databases-and-caches/choreo-managed-mysql-databases.md + - Choreo-Managed Cache: manage-databases-and-caches/choreo-managed-caches.md + - Add Choreo-Managed Databases and Caches to the Marketplace: manage-databases-and-caches/add-choreo-managed-databases-and-caches-to-the-marketplace.md + - Choreo-Managed Message Brokers: + - Overview: manage-message-brokers/choreo-managed-message-brokers.md + - Kafka: + - Create Choreo-Managed Kafka Services: manage-message-brokers/create-choreo-managed-kafka-services.md + - Configure a Kafka Service: manage-message-brokers/configure-a-kafka-service.md + - Monitor a Kafka Service: manage-message-brokers/monitor-a-kafka-service.md + - Authentication and Authorization: + - Secure API Access with Asgardeo: authentication-and-authorization/secure-api-access-with-asgardeo.md + - Secure API Access with Azure: authentication-and-authorization/secure-api-access-with-azure-ad.md + - Secure Web Applications with Managed Authentication: authentication-and-authorization/secure-web-applications-with-managed-authentication.md + - Test Secure API Access with Choreo Built-In Security Token Service: authentication-and-authorization/test-secure-api-access-with-choreo-built-in-security-token-service.md + - Pass End-User Attributes to Upstream Services: authentication-and-authorization/pass-end-user-attributes-to-upstream-services.md + - Configure Mutual TLS Between Components: authentication-and-authorization/configure-mutual-tls-between-components.md + - Secure Communication Between the Choreo Gateway and Your Backend with Mutual TLS: authentication-and-authorization/secure-communication-between-the-choreo-gateway-and-your-backend-with-mutual-tls.md + - DevOps and CI/CD: + - Manage Configurations and Secrets: devops-and-ci-cd/manage-configurations-and-secrets.md + - View Runtime Details: devops-and-ci-cd/view-runtime-details.md + - Configure Container Resources, Commands, and Arguments: devops-and-ci-cd/configure-container-resources-commands-and-arguments.md + - Set Up Health Checks: devops-and-ci-cd/set-up-health-checks.md + - Autoscale: + - Autoscale Component Replicas: devops-and-ci-cd/autoscale/autoscale-component-replicas.md + - Autoscale Components with Scale-to-Zero: devops-and-ci-cd/autoscale/autoscale-components-with-scale-to-zero.md + - Configure Storage: devops-and-ci-cd/configure-storage.md + - Manage Environments: devops-and-ci-cd/manage-environments.md + - Manage Configuration Groups: devops-and-ci-cd/manage-configuration-groups.md + - Manage Continuous Deployment Pipelines: devops-and-ci-cd/manage-continuous-deployment-pipelines.md + - Configure VPNs on the Choreo Cloud Data Plane: devops-and-ci-cd/configure-vpns-on-the-choreo-cloud-data-plane.md + - Testing: + - Test REST Endpoints via the OpenAPI Console: testing/test-rest-endpoints-via-the-openapi-console.md + - Test GraphQL Endpoints via the GraphQL Console: testing/test-graphql-endpoints-via-the-graphql-console.md + - Test WebSocket Endpoints via the WebSocket Console: testing/test-websocket-endpoints-via-the-websocket-console.md + - Test APIs with cURL: testing/test-apis-with-curl.md + - Test APIs with Choreo API Chat: testing/test-apis-with-choreo-apichat.md + - Test Components with Test Runner: testing/test-components-with-test-runner.md + - Consuming Services: + - Consume a Service: + - Consume a service secured with API key: consuming-services/consume-an-api-key-secured-service.md + - Consume a service secured with OAuth2: consuming-services/consume-an-oauth2-secured-service.md + - Manage Application: consuming-services/manage-application.md + - Share Applications: consuming-services/share-applications.md + - Manage Subscription: consuming-services/manage-subscription.md + - Generate an Access Token: consuming-services/generate-an-access-token.md + - API Management: + - Lifecycle Management: api-management/lifecycle-management.md + - Documents: api-management/documents.md + - API Rate Limiting: api-management/api-rate-limiting.md + - API Policies: + - About API Policies: api-management/api-policies/about-api-policies.md + - Attach and Manage Policies: api-management/api-policies/attach-and-manage-policies.md + - Apply Advanced Settings on Mediation Policies: api-management/api-policies/apply-advanced-settings-on-mediation-policies.md + - Control API Visibility: api-management/control-api-visibility.md + - Manage API Traffic: + - Assign Subscription Plans to APIs: api-management/manage-api-traffic/assign-subscription-plans-to-apis.md + - Subscribe to an API with a Subscription Plan: api-management/manage-api-traffic/subscribe-to-an-api-with-a-subscription-plan.md + - Rename API Display Name: api-management/rename-api-display-name.md + - Monitoring and Insights: + - Observability Overview: monitoring-and-insights/observability-overview.md + - Alert Overview: monitoring-and-insights/alerts-overview.md + - Delivery Insights: + - Configure DORA Metrics: monitoring-and-insights/delivery-insights/configure-dora-metrics.md + - View DORA Metrics: monitoring-and-insights/delivery-insights/view-dora-metrics.md + - Usage Insights: + - Insights Overview: monitoring-and-insights/insights-overview.md + - Generate Custom Reports: monitoring-and-insights/generate-custom-reports.md + - Cost Insights: monitoring-and-insights/cost-optimization.md + - View Logs: monitoring-and-insights/view-logs.md + - Work with the Choreo Insights API: + - Access the Choreo Insights API: monitoring-and-insights/work-with-choreo-insights-api/access-the-choreo-insights-api.md + - Choreo Insights API: monitoring-and-insights/work-with-choreo-insights-api/choreo-insights-api.md + - Integrate Choreo with Moesif: monitoring-and-insights/integrate-choreo-with-moesif.md + - Choreo CLI: + - Choreo CLI Overview: choreo-cli/choreo-cli-overview.md + - Get Started with the Choreo CLI: choreo-cli/get-started-with-the-choreo-cli.md + - Manage Authentication with Personal Access Tokens: choreo-cli/manage-authentication-with-personal-access-tokens.md + - Administer: + - Control Access in the Choreo Console: administer/control-access-in-the-choreo-console.md + - Configure a Custom Domain for Your Organization: administer/configure-a-custom-domain-for-your-organization.md + - Configure Enterprise Login: administer/configure-enterprise-login.md + - Configure an External IdP: + - Configure Asgardeo as an External IdP: administer/configure-an-external-idp/configure-asgardeo-as-an-external-idp.md + - Configure Azure as an External IdP: administer/configure-an-external-idp/configure-azure-ad-as-an-external-idp.md + - Create API Subscription Plans: administer/create-api-subscription-plans.md + - Configure Approvals for Choreo Workflows: administer/configure-approvals-for-choreo-workflows.md + - Review Workflow Approval Requests: administer/review-workflow-approval-requests.md + - Configure a User Store with the Built-In Identity Provider: administer/configure-a-user-store-with-built-in-idp.md + - Developer Portal: + - Customize the Developer Portal: administer/customize-the-developer-portal.md + - Configure Self-Sign-Up: administer/configure-self-sign-up.md + - Manage Members of an Organization: administer/manage-members-of-an-organization.md + - Control Egress Traffic for Your Organization: administer/control-egress-traffic-for-your-organization.md + - References: + - FAQ: references/faq.md + - Choreo Limitations: references/choreo-limitations.md + - Troubleshoot Choreo: references/troubleshoot-choreo.md + - Private Data Plane Security Levels: references/private-data-plane-security-levels.md + - Private Data Plane Management Models: references/private-data-plane-management-models.md + - Choreo Platform Service Billing and Upgrades: references/choreo-platform-services-billing-and-upgrades.md + +# Extensions +# Extensions +markdown_extensions: + - markdown.extensions.admonition + - markdown.extensions.def_list + - markdown.extensions.footnotes + - markdown.extensions.toc: + permalink: true + toc_depth: 3 + - pymdownx.arithmatex + - pymdownx.betterem: + smart_enable: all + - pymdownx.caret + - pymdownx.critic + - pymdownx.details + - pymdownx.emoji: + emoji_generator: !!python/name:pymdownx.emoji.to_svg + - pymdownx.highlight: + anchor_linenums: true + pygments_lang_class: true + - pymdownx.keys + - pymdownx.mark + - pymdownx.smartsymbols + - pymdownx.superfences + - pymdownx.tabbed: + alternate_style: true + - pymdownx.tasklist: + custom_checkbox: true + - pymdownx.tilde + - pymdownx.snippets: + base_path: docs + - attr_list +plugins: + - search + - include-markdown + - glightbox + - open-in-new-tab + - markdownextradata: {} + - redirects: + redirect_maps: + "tutorials/create-your-first-rest-api.md": "https://wso2.com/choreo/docs/get-started/tutorials/create-your-first-rest-api/" + "tutorials/connect-your-own-github-repository-to-choreo.md": "https://wso2.com/choreo/docs/manage-repository/connect-your-own-github-repository-to-choreo/" + "tutorials/construct-statements.md": "https://wso2.com/choreo/docs/develop/explore-code-editor/construct-statements/" + "tutorials/connect-your-existing-ballerina-project-to-choreo.md": "https://wso2.com/choreo/docs/manage-repository/connect-your-existing-ballerina-project-to-choreo/" + "tutorials/configure-automatic-deployment.md": "https://wso2.com/choreo/docs/deploy/configure-automatic-deployment/" + "tutorials/map-data.md": "https://wso2.com/choreo/docs/develop/explore-code-editor/map-data/" + "rest-api.md": "https://wso2.com/choreo/docs/develop/components/rest-api/" + "api-proxies.md": "https://wso2.com/choreo/docs/develop/components/api-proxy/" + "api-proxies/api-proxy.md": "https://wso2.com/choreo/docs/develop/components/api-proxy/" + "webhook.md": "https://wso2.com/choreo/docs/develop/components/webhook/" + "scheduled-tasks.md": "https://wso2.com/choreo/docs/develop/components/scheduled-trigger/" + "manual-triggers.md": "https://wso2.com/choreo/docs/develop/components/manual-trigger/" + "graphql-api.md": "https://wso2.com/choreo/docs/develop/components/graphql-api/" + "developer-portal/developer-portal.md": "https://wso2.com/choreo/docs/consume/developer-portal/" + "developer-portal/manage-application.md": "https://wso2.com/choreo/docs/consume/manage-application/" + "developer-portal/manage-subscription.md": "https://wso2.com/choreo/docs/consume/manage-subscription/" + "developer-portal/test-api.md": "https://wso2.com/choreo/docs/consume/test-api/" + "insights/view-api-insights.md": "https://wso2.com/choreo/docs/observe-and-analyze/analyze/view-api-insights/" + "insights/generate-custom-reports.md": "https://wso2.com/choreo/docs/observe-and-analyze/analyze/generate-custom-reports/" + "insights/configure-alerts.md": "https://wso2.com/choreo/docs/observe-and-analyze/analyze/configure-alerts/" + "insights/choreo-insights-api.md": "https://wso2.com/choreo/docs/observe-and-analyze/analyze/choreo-insights-api/" + "insights/programmatic-access-choreo-insights-api.md": "https://wso2.com/choreo/docs/observe-and-analyze/analyze/programmatic-access-choreo-insights-api/" + "administration/connect-to-an-external-identity-provider.md": "https://wso2.com/choreo/docs/administer/connect-to-an-external-identity-provider/" + "administration/customize-developer-portal-domain.md": "https://wso2.com/choreo/docs/administer/customize-developer-portal-domain/" + "administration/configure-a-custom-domain-for-apis.md": "https://wso2.com/choreo/docs/administer/configure-a-custom-domain-for-apis/" + "administration/customize-the-developer-portal.md": "https://wso2.com/choreo/docs/administer/customize-the-developer-portal/" + "administration/configure-enterprise-login.md": "https://wso2.com/choreo/docs/administer/configure-enterprise-login/" + "administration/configure-developer-portal-self-sign-up.md": "https://wso2.com/choreo/docs/administer/configure-developer-portal-self-sign-up/" + "observability/observability-overview.md": "https://wso2.com/choreo/docs/observe-and-analyze/observe/observability-overview/" + "observability/root-cause-analysis.md": "https://wso2.com/choreo/docs/observe-and-analyze/observe/root-cause-analysis/" + "references/performance-analysis.md": "https://wso2.com/choreo/docs/develop/run-and-test/forecast-performance-metrics/" + "references/alerting.md": "https://wso2.com/choreo/docs/alerts/" + "references/manage-connectors.md": "https://wso2.com/choreo/docs/develop/advanced-topics/manage-connectors/" + "references/handle-non-ballerina-files-in-choreo.md": "https://wso2.com/choreo/docs/develop/explore-code-editor/handle-non-ballerina-files-in-choreo/" + "references/define-configurable-variables.md": "https://wso2.com/choreo/docs/develop/explore-code-editor/define-configurable-variables/" + "references/connect-with-protected-third-party-applications.md": "https://wso2.com/choreo/docs/references/connect-with-protected-third-party-applications/" + "develop/components/api-proxies/policies.md": "https://wso2.com/choreo/docs/develop/api-policies/policies/" + "get-started/what-is-choreo.md": "https://wso2.com/choreo/docs/what-is-choreo/" + "get-started/quick-start-guide.md": "https://wso2.com/choreo/docs/quick-start-guides/build-your-first-cloud-native-application-with-choreo/" + "get-started/build-your-first-cloud-native-application-with-choreo.md": "https://wso2.com/choreo/docs/quick-start-guides/deploy-a-web-application-that-consumes-a-backend-service/" + "get-started/tutorials/create-your-first-rest-api.md": "https://wso2.com/choreo/docs/quick-start-guides/build-your-first-cloud-native-application-with-choreo/" + "get-started/tutorials/create-your-first-rest-api-proxy.md": "https://wso2.com/choreo/docs/quick-start-guides/expose-a-service-as-a-managed-api-with-choreo-api-manager/" + "get-started/tutorials/create-your-first-webhook.md": "https://wso2.com/choreo/docs/develop-components/develop-a-webhook/" + "get-started/tutorials/create-your-first-integration-as-an-api.md": "https://wso2.com/choreo/docs/quick-start-guides/build-your-first-integration-with-choreo-ipaas/" + "get-started/tutorials/create-your-first-event-triggered-integration.md": "https://wso2.com/choreo/docs/develop-components/develop-integrations/develop-an-event-triggered-integration/" + "get-started/tutorials/secure-an-api-with-role-based-access-control.md": "https://wso2.com/choreo/docs/tutorials/secure-an-api-with-role-based-access-control/" + "get-started/tutorials/create-your-first-containerized-service-component.md": "https://wso2.com/choreo/docs" + "get-started/tutorials/deploy-a-containerized-application-as-an-event-triggered-integration.md": "https://wso2.com/choreo/docs/develop-components/deploy-a-containerized-application/" + "develop/components/rest-api.md": "https://wso2.com/choreo/docs/develop-components/develop-services/develop-a-rest-api/" + "develop/components/api-proxy.md": "https://wso2.com/choreo/docs/develop-components/develop-a-rest-api-proxy/" + "develop/components/webhook.md": "https://wso2.com/choreo/docs/develop-components/develop-a-webhook/" + "develop/components/scheduled-trigger.md": "https://wso2.com/choreo/docs/develop-components/develop-integrations/develop-a-scheduled-integration/" + "develop/components/manual-trigger.md": "https://wso2.com/choreo/docs" + "develop/components/graphql-api.md": "https://wso2.com/choreo/docs/develop-components/develop-services/develop-a-ballerina-graphql-api/" + "develop/components/service.md": "https://wso2.com/choreo/docs/develop-components/develop-services/develop-a-service/" + "develop/manage-repository/connect-your-own-github-repository-to-choreo.md": "https://wso2.com/choreo/docs/develop-components/develop-components-with-git/" + "develop/run-and-test/forecast-performance-metrics.md": "https://wso2.com/choreo/docs" + "develop/api-policies/policies.md": "https://wso2.com/choreo/docs/api-management/api-policies/" + "develop/api-policies/create-a-policy.md": "https://wso2.com/choreo/docs/api-management/api-policies/" + "develop/api-policies/attach-policies.md": "https://wso2.com/choreo/docs/api-management/api-policies/" + "deploy/deploy-a-ballerina-application.md": "https://wso2.com/choreo/docs" + "deploy/deploy-a-containerized-application.md": "https://wso2.com/choreo/docs/develop-components/deploy-a-containerized-application/" + "deploy/devops/runtime.md": "https://wso2.com/choreo/docs/devops-and-ci-cd/view-runtime-details/" + "deploy/devops/containers.md": "https://wso2.com/choreo/docs/devops-and-ci-cd/configure-container-resources-commands-and-arguments/" + "deploy/devops/configs-and-secrets.md": "https://wso2.com/choreo/docs/devops-and-ci-cd/manage-configurations-and-secrets/" + "deploy/devops/health-checks.md": "https://wso2.com/choreo/docs/devops-and-ci-cd/set-up-health-checks/" + "deploy/devops/scaling.md": "https://wso2.com/choreo/docs/devops-and-ci-cd/autoscale-component-replicas/" + "deploy/devops/storage.md": "https://wso2.com/choreo/docs/devops-and-ci-cd/configure-storage/" + "test/invoke-apis-via-console.md": "https://wso2.com/choreo/docs/testing/test-rest-endpoints-via-the-openapi-console/" + "test/open-api-console.md": "https://wso2.com/choreo/docs/testing/test-rest-endpoints-via-the-openapi-console/" + "test/curl.md": "https://wso2.com/choreo/docs/devops-and-ci-cd/configure-storage/" + "test/graphql-console.md": "https://wso2.com/choreo/docs/testing/test-graphql-endpoints-via-the-graphql-console/" + "manage/api-management.md": "https://wso2.com/choreo/docs/api-management/lifecycle-management/" + "manage/lifecycle.md": "https://wso2.com/choreo/docs/api-management/lifecycle-management/" + "manage/api-security/pass-end-user-attributes-to-the-backend.md": "https://wso2.com/choreo/docs/api-management/api-rate-limiting/" + "manage/api-rate-limiting.md": "https://wso2.com/choreo/docs/api-management/api-rate-limiting/" + "consume/developer-portal.md": "https://wso2.com/choreo/docs" + "consume/manage-application.md": "https://wso2.com/choreo/docs/consuming-services/manage-application/" + "consume/manage-subscription.md": "https://wso2.com/choreo/docs/consuming-services/manage-subscription/" + "consume/test-api.md": "https://wso2.com/choreo/docs/testing/test-rest-endpoints-via-the-openapi-console/" + "marketplace.md": "https://wso2.com/choreo/docs/choreo-concepts/choreo-marketplace/" + "observe-and-analyze/observe/observability-overview.md": "https://wso2.com/choreo/docs/monitoring-and-insights/observability-overview/" + "observe-and-analyze/observe/root-cause-analysis.md": "https://wso2.com/choreo/docs" + "observe-and-analyze/analyze/view-api-insights.md": "https://wso2.com/choreo/docs/monitoring-and-insights/view-api-insights/" + "observe-and-analyze/analyze/generate-custom-reports.md": "https://wso2.com/choreo/docs/monitoring-and-insights/generate-custom-reports/" + "observe-and-analyze/analyze/configure-alerts.md": "https://wso2.com/choreo/docs/monitoring-and-insights/alerts/configure-alerts/" + "observe-and-analyze/analyze/choreo-insights-api.md": "https://wso2.com/choreo/docs/monitoring-and-insights/work-with-choreo-insights-api/choreo-insights-api/" + "observe-and-analyze/analyze/programmatic-access-choreo-insights-api.md": "https://wso2.com/choreo/docs/monitoring-and-insights/work-with-choreo-insights-api/access-the-choreo-insights-api/" + "observe-and-analyze/analyze/dora-metrics/configure-cio-dashboard.md": "https://wso2.com/choreo/docs/monitoring-and-insights/engineering-insights/configure-cio-dashboard/" + "observe-and-analyze/analyze/dora-metrics/view-dora-metrics.md": "https://wso2.com/choreo/docs/monitoring-and-insights/engineering-insights/view-dora-metrics/" + "alerts.md": "https://wso2.com/choreo/docs/monitoring-and-insights/alerts/configure-alerts/" + "ipaas/get-started-with-choreo-ipaas.md": "https://wso2.com/choreo/docs/quick-start-guides/build-your-first-integration-with-choreo-ipaas/" + "ipaas/ballerina/develop-integrations-with-ballerina.md": "https://wso2.com/choreo/docs/quick-start-guides/build-your-first-integration-with-choreo-ipaas/" + "ipaas/ballerina/create-your-first-event-triggered-integration.md": "https://wso2.com/choreo/docs/develop-integrations/develop-an-event-triggered-integration/" + "ipaas/micro-integrator/develop-integrations-with-integration-studio.md": "https://wso2.com/choreo/docs/develop-integrations/develop-an-integration-with-integration-studio/" + "ipaas/micro-integrator/create-your-first-integration.md": "https://wso2.com/choreo/docs/quick-start-guides/build-your-first-integration-with-choreo-ipaas/" + "administer/connect-to-an-external-identity-provider.md": "https://wso2.com/choreo/docs" + "administer/configure-developer-portal-self-sign-up.md": "https://wso2.com/choreo/docs/administer/configure-self-sign-up/" + "administer/organization.md": "https://wso2.com/choreo/docs/choreo-concepts/organization/" + "reference/connect-with-protected-third-party-applications.md": "https://wso2.com/choreo/docs/troubleshoot/faq/#q-how-can-i-connect-a-choreo-component-with-a-protected-third-party-application" + "quick-start-guides/build-your-first-integration-with-choreo-ipaas.md": "https://wso2.com/choreo/docs/tutorials/build-your-first-integration/" + "quick-start-guides/expose-a-service-as-a-managed-api-with-choreo-api-manager.md": "https://wso2.com/choreo/docs/tutorials/expose-a-service-as-a-managed-api/" + "monitoring-and-insights/engineering-insights/configure-cio-dashboard.md": "https://wso2.com/choreo/docs/monitoring-and-insights/delivery-insights/configure-dora-metrics/" + "monitoring-and-insights/engineering-insights/view-dora-metrics.md": "https://wso2.com/choreo/docs/monitoring-and-insights/delivery-insights/view-dora-metrics/" + "monitoring-and-insights/view-api-insights.md": "https://wso2.com/choreo/docs/monitoring-and-insights/usage-insights/" + "devops-and-ci-cd/autoscale-component-replicas.md": "https://wso2.com/choreo/docs/devops-and-ci-cd/autoscale/autoscale-component-replicas" + "testing/test-apis-with-choreo-testgpt.md": "https://wso2.com/choreo/docs/testing/test-apis-with-choreo-apichat/" + "develop-integrations/develop-an-event-triggered-integration.md": "https://wso2.com/choreo/docs/develop-components/develop-integrations/develop-an-event-handler/" + "develop-integrations/develop-a-scheduled-integration.md": "https://wso2.com/choreo/docs/develop-components/develop-integrations/develop-a-scheduled-task/" + "develop-components/develop-a-rest-api-proxy.md": "https://wso2.com/choreo/docs/develop-components/develop-proxy/" + "devops-and-ci-cd/builds-and-deployments.md": "https://wso2.com/choreo/docs/choreo-concepts/ci-cd/" + "troubleshoot/faq.md": "https://wso2.com/choreo/docs/references/faq/" + "develop-components/develop-services/develop-a-rest-api.md": "https://wso2.com/choreo/docs/develop-components/develop-services/develop-a-service/" + "develop-components/develop-services/develop-a-go-rest-api.md": "https://wso2.com/choreo/docs/develop-components/develop-services/develop-a-service-with-docker/" + "develop-components/develop-services/develop-a-grpc-service.md": "https://wso2.com/choreo/docs/develop-components/develop-services/expose-a-grpc-endpoint-via-a-service/" + "develop-components/develop-services/develop-a-tcp-service.md": "https://wso2.com/choreo/docs/develop-components/develop-services/expose-a-tcp-server-via-a-service/" + "develop-components/develop-services/develop-a-udp-service.md": "https://wso2.com/choreo/docs/develop-components/develop-services/expose-a-udp-server-via-a-service/" + "develop-components/develop-services/develop-a-ballerina-rest-api.md": "https://wso2.com/choreo/docs/develop-components/develop-services/develop-a-ballerina-service/" + "develop-components/develop-services/develop-a-ballerina-graphql-api.md": "https://wso2.com/choreo/docs/develop-components/develop-services/expose-a-ballerina-graphql-endpoint-via-a-service/" + "quick-start-guides/build-your-first-cloud-native-application-with-choreo.md": "https://wso2.com/choreo/docs/quick-start-guides/deploy-a-web-application-that-consumes-a-backend-service/" + "choreo-concepts/configuration-management.md": "https://wso2.com/choreo/docs/devops-and-ci-cd/manage-configurations-and-secrets/" + "develop-components/develop-a-web-application.md": "https://wso2.com/choreo/docs/develop-components/develop-web-applications/build-and-deploy-a-single-page-web-application/" + "administer/configure-a-custom-domain-for-apis.md": "https://wso2.com/choreo/docs/administer/configure-a-custom-domain-for-your-organization/" + "administer/customize-developer-portal-domain.md": "https://wso2.com/choreo/docs/administer/configure-a-custom-domain-for-your-organization/" + "authentication-and-authorization/access-control/control-access-in-the-choreo-console.md": "https://wso2.com/choreo/docs/administer/control-access-in-the-choreo-console/" + "authentication-and-authorization/secure-communication-between-the-choreo-gateway-and-your-backend.md": "https://wso2.com/choreo/docs/authentication-and-authorization/secure-communication-between-the-choreo-gateway-and-your-backend-with-mutual-tls/" + "develop-components/sharing-and-reusing/share-and-reuse-services.md": "https://wso2.com/choreo/docs/develop-components/sharing-and-reusing/use-a-connection-in-your-service/" + "develop-components/sharing-and-reusing/share-and-reuse-web-applications.md": "https://wso2.com/choreo/docs/develop-components/sharing-and-reusing/use-a-connection-in-your-web-application/" + "manage-databases-and-caches/choreo-managed-redis-datastores.md": "https://wso2.com/choreo/docs/manage-databases-and-caches/choreo-managed-caches/" + "monitoring-and-insights/usage-insights.md": "https://wso2.com/choreo/docs/monitoring-and-insights/insights-overview/" + "develop-components/configure-mutual-tls-between-components.md": "https://wso2.com/choreo/docs/authentication-and-authorization/configure-mutual-tls-between-components/" + "api-management/api-policies.md": "https://wso2.com/choreo/docs/api-management/api-policies/about-api-policies/" + "develop-components/develop-services/expose-a-websocket-endpoint-via-a-nodejs-service.md": "https://wso2.com/choreo/docs/develop-components/develop-services/expose-a-websocket-endpoint-via-a-service/" + "manage-databases-and-caches/billing-for-platform-services.md": "https://wso2.com/choreo/docs/references/choreo-platform-services-billing-and-upgrades/" + "consuming-services/consuming-a-sevice-oauth2.md": "https://wso2.com/choreo/docs/consuming-services/consuming-a-sevice/" + +extra_css: + # - assets/lib/highlightjs/default.min.css + # - assets/css/theme.css + # - assets/css/prism.css + # - assets/lib/json-formatter/json-formatter.css + + - assets/lib/highlightjs/styles/vs.min.css + - assets/css/blue-palette-alt2.css + - assets/css/choreotheme.css + - assets/lib/json-formatter/json-formatter.css + - assets/css/config-catalog.css + - assets/lib/fontawesome-free-6.3.0-web/css/all.min.css +extra_javascript: + - assets/lib/json-formatter/json-formatter.umd.js + - assets/lib/highlightjs/highlight.min.js + # - assets/js/theme.js + #- assets/js/prism-ballerina.js + - assets/js/choreotheme.js +extra: + social: + - icon: fontawesome/brands/github + link: https://github.com/wso2 + version: + provider: mike + # Perspective dropdown configurations + show_perspective_dropdown: true + developer_docs_path: /choreo/docs/developer/ + pe_docs_path: /choreo/docs/platform-engineer/ +#site_version: 1.0.0 +#base_path: http://localhost:8000 + diff --git a/en/docs/administer/configure-approvals-for-choreo-workflows.md b/en/docs/administer/configure-approvals-for-choreo-workflows.md deleted file mode 100644 index 6bb556e0d..000000000 --- a/en/docs/administer/configure-approvals-for-choreo-workflows.md +++ /dev/null @@ -1,37 +0,0 @@ -# Configure Approvals for Choreo Workflows - -Choreo allows you to configure approval processes for specific workflows within the platform. An approval process for a workflow ensures that critical or sensitive changes are properly managed and controlled. - -Choreo currently allows you to configure approvals for environment promotion workflows, with support for API subscription approvals coming soon. - -## Permissions to review and respond to approval requests - -To review and respond to approval requests, a user must have the following permissions. Administrators must ensure that users designated to review and respond to approval requests have these permissions: - - - **WORKFLOW-MANAGEMENT**: Grants access to view and approve workflow requests. Each workflow type has a separate permission. - - **PROJECT-MANAGEMENT**: Grants access to view and approve workflow requests. This is the same permission used to update or delete projects. - -## Set up an approval process for a workflow - -To set up an approval process for a workflow, follow these steps: - -!!! note - - You must have administrator privileges in Choreo to configure workflow approvals. - - Administrators can designate specific roles and assignees to review and respond to requests associated with each workflow. - -1. Sign in to the [Choreo Console](https://console.choreo.dev/). -2. In the Choreo Console header, go to the **Organization** list and select your organization. -3. In the left navigation menu, click **Settings**. This opens the organization-level settings page. -4. Click the **Workflows** tab. -5. Click the edit icon corresponding to the workflow for which you want to configure an approval. -6. In the **Configure Workflow** dialog that opens, select roles and assignees to review and respond to workflow approval requests. - - - In the **Roles** field, select one or more roles depending on your preference. Any user assigned to these roles can review and respond to requests. - - In the **Assignees** field, select specific users who can review and approve workflow requests. Assignees can be any Choreo user, even if they are not assigned to a selected role. - - !!! info "Important" - Currently, there is no validation to ensure that the specified roles and assignees have the necessary permissions to review and respond to requests. If the [required permissions](#permissions-to-review-and-respond-to-approval-requests) are not correctly configured, some users may receive email notifications but will be unable to review the requests. - -7. Click **Save**. This configures and enables the approval process for the workflow. - -Once you configure an approval process for a workflow, developers must [submit a request for approval to use the workflow](../develop-components/submit-and-manage-workflow-approval-requests.md). An authorized assignee must then [review and approve the request](./review-workflow-approval-requests.md) for a developer to proceed with the task related to the workflow. Depending on the workflow, there can be tasks where the execution may occur automatically upon approval. diff --git a/en/docs/assets/img/administer/create-subscription-plan.png b/en/docs/assets/img/administer/create-subscription-plan.png deleted file mode 100644 index 7449bcea4..000000000 Binary files a/en/docs/assets/img/administer/create-subscription-plan.png and /dev/null differ diff --git a/en/docs/assets/img/api-management/manage-api-traffic/enable-toggle.png b/en/docs/assets/img/api-management/manage-api-traffic/enable-toggle.png deleted file mode 100644 index 5fbd0630f..000000000 Binary files a/en/docs/assets/img/api-management/manage-api-traffic/enable-toggle.png and /dev/null differ diff --git a/en/docs/assets/img/monitoring-and-insights/alerts/alert-configuration.png b/en/docs/assets/img/monitoring-and-insights/alerts/alert-configuration.png deleted file mode 100644 index c7e5d1b02..000000000 Binary files a/en/docs/assets/img/monitoring-and-insights/alerts/alert-configuration.png and /dev/null differ diff --git a/en/docs/choreo-concepts/resource-hierarchy.md b/en/docs/choreo-concepts/resource-hierarchy.md deleted file mode 100644 index a9f1f5c63..000000000 --- a/en/docs/choreo-concepts/resource-hierarchy.md +++ /dev/null @@ -1,32 +0,0 @@ -# Resource Hierarchy - -The following diagram depicts the high-level resources and their relationships in Choreo. - -![Resource hierarchy](../assets/img/choreo-concepts/resource-hierarchy.png){.cInlineImage-full} - - -## Organizations and data planes - -Data planes are connected to the organization and are available for all the projects in the organization. When you create an environment in a project, the data plane connected to the organization is linked with an automatically generated Kubernetes namespace. - -## Environments and data planes - -Choreo allows multiple Kubernetes clusters to be associated with an environment. - -This allows you to build highly resilient and resource-efficient solutions that utilize multiple clusters. Choreo synchronizes your applications and workloads between associated clusters in an environment. This allows you to perform multi-cluster deployment with a single click. - -The following diagram depicts how multiple clusters associate with different environments: - -![Environments and dataplanes](../assets/img/choreo-concepts/environments-and-dataplanes.png){.cInlineImage-full} - -!!! info "Note" - It is not necessary to use a different cluster per environment. You can create multiple environments on the same cluster. The above diagram is only an example of a specific solution. Your application architecture may require an entirely different configuration than what is depicted in the diagram. - - -## Components and environments - -Components belong to a project in Choreo and environments are provisioned per project as well. When a component is deployed, it is deployed as a container to the specified environment. Once deployed, you can promote the container image across the environments available in the project. - - - - diff --git a/en/docs/choreo-samples/quick-deploy-a-sample.md b/en/docs/choreo-samples/quick-deploy-a-sample.md deleted file mode 100644 index 261f2c13c..000000000 --- a/en/docs/choreo-samples/quick-deploy-a-sample.md +++ /dev/null @@ -1,33 +0,0 @@ -# Quick Deploy a Sample - -Choreo provides a quick deploy option for samples, allowing you to deploy a sample with a single click. This capability lets you quickly explore the sample. - -## Prerequisites - -Before you start using the samples, complete the following steps: - -- Sign in to Choreo and go to your project **Overview** page. - - If you're signing in for the first time, follow these steps to create an organization and then create a project: - 1. Go to [https://console.choreo.dev/](https://console.choreo.dev/), and sign in using your preferred method. - 2. Enter a unique organization name. For example, `Stark Industries`. - 3. Read and accept the privacy policy and terms of use. - 4. Click **Create**. This creates the organization and takes you to its **Overview** page. - 5. On the organization home page, click **+ Create Project**. - 6. Enter a display name, unique name, and description for the project. - 7. Click **Create**. This creates the project and takes you to its **Overview** page. - -## Try out quick deploy - -To quickly deploy a sample, follow these steps: - -1. Sign in to the [Choreo Console](https://console.choreo.dev/). -2. On the Choreo Console header, go to the **Project** list and select your project. This opens the project **Overview** page. -3. On the project **Overview** page, go to the **Get Started with a Sample** section. You will see a selection of samples. -4. To see the complete collection of samples, click **View All Samples**. -5. Hover over a sample of your choice and click **Quick Deploy**. This creates the component and deploys it automatically. - -Once you quick deploy a sample, you can follow one of the following post-deployment actions given below depending on the component type: - -- **For services**: Go to the **Test Console** to test the deployed service. -- **For web applications**: Open the deployed web application using the provided URL. -- **For manual tasks and scheduled tasks:** Go to the **Execute** page and run the task. For scheduled tasks, you can also find the cron schedule on the **Overview** page. diff --git a/en/docs/choreo-samples/samples-overview.md b/en/docs/choreo-samples/samples-overview.md deleted file mode 100644 index ed95d8a95..000000000 --- a/en/docs/choreo-samples/samples-overview.md +++ /dev/null @@ -1,36 +0,0 @@ -# Samples Overview - -Choreo provides an extensive collection of samples for a wide range of use cases. You can quickly deploy and explore these samples to easily understand the core functionalities of the platform. - -## Prerequisites - -Before you use the samples, complete the following steps: - -- If you're signing in for the first time, follow these steps to create an organization and then create a project: - 1. Go to the [Choreo Console](https://console.choreo.dev/) and sign in using Google, GitHub, or Microsoft. - 2. Enter a unique organization name. For example, `Stark Industries`. - 3. Read and accept the privacy policy and terms of use. - 4. Click **Create**. This creates an organization and takes you to its **Overview*** page. - 5. On the organization home page, click **+ Create Project**. - 6. Enter a display name, unique name, and description for the project. - 7. Click **Create**. This creates the project and takes you to its **Overview** page. - -## Explore the Choreo samples collection - -You can filter and explore Choreo's sample collection based on your preference. - -To view available samples, follow these steps: - -1. Sign in to the [Choreo Console](https://console.choreo.dev/). -2. In the Choreo Console header, go to the **Project** list and select your project to open its **Overview** page. -3. On the project **Overview** page, go to the **Get Started with a Sample** section. You will see a selection of samples. -4. To see the complete collection of samples, click **View All Samples**. - - -When you view all samples, you can filter and search for samples by the following criteria: - - - **Buildpack**: Filters by the technology used. For example, Ballerina, NodeJS, Docker, etc. - - **Component Type**: Filters by the component type. For example, service, web application, scheduled tasks, manual tasks, etc. - - **Tags**: Use tags like REST, HTTP, or GraphQL to find samples with specific functionalities or integrations. - -You can either quick deploy a sample or access its source code on GitHub. For details on quick deploying a sample, see [Quick Deploy a Sample](./quick-deploy-a-sample.md). diff --git a/en/docs/consuming-services/consuming-a-sevice.md b/en/docs/consuming-services/consuming-a-sevice.md deleted file mode 100644 index dce3489dc..000000000 --- a/en/docs/consuming-services/consuming-a-sevice.md +++ /dev/null @@ -1,180 +0,0 @@ -# Consume a Service - -Choreo is a platform that allows you to create, deploy, and consume services seamlessly. The Choreo Developer Portal simplifies discovering and using APIs for API consumers. - -Typically, an application developer who may be internal or external to your organization would want to consume the APIs published in the Developer Portal to develop their applications. In this guide, you will learn how to discover, generate credentials, and test the consumption of a service published in the Choreo Developer Portal. You will also learn how to invoke the service via a web application. - -This guide walks you through the following steps: - -- Create an application in the Developer Portal and generate credentials for the application. -- Subscribe the API to the application. -- Consume a published REST API via your web application. - -## Prerequisites - -Before you try out this guide, if you do not have a published service that you would want to consume via the Developer Portal, follow [Develop a Service](../develop-components/develop-services/develop-a-service.md) documentation to publish and deploy a sample REST API. - -## Discover APIs - -In the Choreo Developer Portal, developers can use the search option to find APIs by name. The APIs and services that are created and published through the Choreo Console become visible in the Developer Portal depending on the API's visibility as follows: - - - **Public**: The API is **visible to all** in the developer portal. - - - **Private**: The API is visible to the **users who only sign in to the Developer Portal**. - - - **Restricted**: The API is **visible to only the user that has the roles that you specify**. This option helps developers to enforce fine-grained access control to the API. - -To learn more about API visibility, see [Control API Visibility](../api-management/control-api-visibility.md). - -The Choreo Developer Portal lists APIs based on their major version. - -![Developer Portal APIs](../assets/img/consume/developer-portal-apis.png) - -The overview page of an API displays the subscribed versions of the API along with the respective subscription details such as the subscribed application and the application creation date. - -![API overview](../assets/img/consume/api-overview.png) - -!!! tip - If you want to use an API, the recommended approach is to use the latest version of it. You can copy the major version pattern provided as the value of **Endpoints(s)** on the API overview page and use it in your client application. This ensures that your application always invokes the latest API version. - -## Create an application - -{% include "create-an-application.md" %} - -## Subscribe to an API - -{% include "create-a-subscription.md" %} - -## Consume the API via your web application - -You can invoke the API/service using the credentials you created above. Since Choreo services are secured, you need to invoke the services securely with the help of your IdP. To invoke the API/service you created securely, you need to follow the steps below: - -1. Create a web application in Choreo. -2. Create an OAuth application in the IdP. -3. Configure the web application to authenticate the API/service invocations from the IdP, and securely invoke the service/API in Choreo. -4. Deploy the web application. - -In this guide, you will be using the following products and examples: - -- WSO2 Asgardeo as the IdP -- [choreo-samples/reading-list-app/reading-list-front-end](https://github.com/wso2/choreo-samples/tree/main/reading-list-app/reading-list-front-end) as the web application. This is a React SPA that invokes the service using Axios. This web application is configured to read the -[choreo-samples/reading-list-app/reading-list-service](https://github.com/wso2/choreo-samples/tree/main/reading-list-app/reading-list-service) as the service. You can modify this web application to read your service, or [deploy the choreo-samples/reading-list-app/reading-list-service](../quick-start-guides/deploy-a-web-application-that-consumes-a-backend-service.md#step-12-configure-the-sample-service-and-publish-it-as-a-rest-api) in Choreo and use it. - -### Step 1: Create a web application component - -!!! info - You can use your own web application implementation in place of the sample web application. For this exercise, let's use the [choreo-samples/reading-list-app/reading-list-front-end](https://github.com/wso2/choreo-samples/tree/main/reading-list-app/reading-list-front-end) as the web application. - -To host the front-end application in Choreo, you must create a web application component. To create a web application component, follow the steps given below. - -1. In the Choreo console, select the project of the reading list application that you created in the previous steps, from the project list located on the header. -2. Click **Create** under the **Component Listing** section to create a new component. -3. On the **Web Application** card, click **Create**. -4. Enter a unique name and a description for the web application. You can enter the name and description given below: - - | **Field** | **Value** | - |-----------------|-------------------------| - | **Name** | `Reading List Web App` | - | **Description** | `Frontend application for the reading list service` | - -5. Click **Next**. -6. To allow Choreo to connect to your GitHub account, click **Authorize with GitHub**. -7. In the **Connect Repository** pane, enter the following information: - - | **Field** | **Description** | - |-----------------------|-----------------------------------------------| - | **GitHub Account** | Your account | - | **GitHub Repository** | **`choreo-samples`** | - | **Branch** | **`main`** | - | **Buildpack** | Click **React** since the frontend is a React application built with Vite| - | **Build Context Path** | **`reading-list-app/reading-list-front-end`** | - | **Build Command** | **`npm install && npm run build`** | - | **Build Output** | **`dist`** | - | **Node Version** | **`18`** | - -9. Click **Create**. This initializes the service with the implementation from your GitHub repository and takes you to the **Overview** page of the component. - -Let's consume the service through the web app. Choreo services are by default secured. To consume a service in Choreo you need an access token. Let's configure the web application to connect to an IdP (For this guide, let's use Asgardeo) to generate an access token for a user. - -### Step 2: Create an OAuth application in the IdP - -To invoke the service/API in Choreo you require a token. To obtain a token you need to create an OAuth application in the IdP. If you use any other IdP other than Asgardeo, create an OAuth application and set the following: - -- **Allowed grant types**: Code -- **Public client**: Mark as a public client in an application. -- **Authorized redirect URLs**: Enter the web app URL you copied earlier. -- **Allowed origins** field: Add the same URLs that you added as authorized redirect URLs. -- **Access Token**: Set JWT as the Token type. - -Choreo uses Asgardeo as the default identity provider for Choreo applications. When you create an application in the Choreo Developer Portal, it automatically creates a corresponding application in Asgardeo. You can go to the Asgardeo application to specify the configurations required for end users to sign in to the front-end application. Follow the steps below to configure the Asgardeo OAuth application: - -1. Access Asgardeo at [https://console.asgardeo.io/](https://console.asgardeo.io/) and sign in with the same credentials with which you signed in to Choreo. -2. Make sure you are in the same organization that you were when you created the application in the Choreo Developer Portal. You can click the **Organization** list in the Asgardeo Console top menu and ensure you are in the correct organization. -3. In the Asgardeo Console's left navigation, click **Applications**. You will see the **readingListApp** that Choreo automatically created for you. -4. Click on the edit icon to edit the application. -5. Click the **Protocol** tab and apply the following changes: - - 1. Under **Allowed grant types**, select **Code**. - 2. Select the **Public client** checkbox. - 3. In the **Authorized redirect URLs** field, enter the web app URL you copied earlier and click the **+** icon to add the entry. - 4. In the **Allowed origins** field, add the same URLs that you added as authorized redirect URLs. - 5. Under **Access Token**, select **JWT** as the **Token type**. - 6. Click **Update**. - -### Step 3: Configure the web application to connect to the IdP and invoke the service - -In this step, you are adding the configurations needed for the web app to successfully invoke the **Reading List Service** REST API. These configurations need to be updated for each environment you deploy the web app. Here you will be updating the configurations for the development environment. - -!!! note - The web application is reading the environment-specific configurations from the `window` object at runtime. This is done via the `config.js` file in the root of the web application. In this section, you will mount the `config.js` file for the development environment. You will need to do the same for other environments as well when you deploy your web application to multiple environments. - -To configure the front-end application, follow the steps given below: - -1. While on the web application component page, click **DevOps** in the left navigation menu and then click **Configs and Secrets**. -2. Click **+ Create**. -3. Select the mount configuration options as follows and click **Next**: - - | **Field** | **Description** | - |-----------------------|-----------------------------------------------| - | **Config Type** | **Config Map** | - | **Mount Type** | **File Mount** | - -4. Specify values as follows for the mount configuration: - - | **Field** | **Description** | - |-----------------------|-----------------------------------------------| - | **Config Name** | **Web App Config** | - | **Mount Path** | **/usr/share/nginx/html/config.js**. Every config that needs to be exposed through the web server should be placed inside `/usr/share/nginx/html/` | - -5. Copy the config details as a JSON file as shown below into the text area. Fill the placeholders with the values you copied from the previous steps as mentioned in the table below: - - ```javascript - window.config = { - redirectUrl: "", - asgardeoClientId: "", - asgardeoBaseUrl: "https://api.asgardeo.io/t/", - choreoApiUrl: "" - }; - ``` - - | **Field** | **Description** | - |-----------------------|-----------------------------------------------| - | **redirectUrl** | The web app URL you copied earlier. | - | **asgardeoClientId** | The **Client ID** of your OAuth application. In Asgardeo, you can find it on the **Protocol** tab of the **readingListApp** application | - | **asgardeoBaseUrl** | Specify the IdP API URL (For example, Asgardeo API URL) with your organization name. i.e., `https://api.asgardeo.io/t/`. | - | **choreoApiUrl** | The reading list service URL. Copy the Public URL of the **Reading List Service** component from the endpoint table in the overview page for the relevant environment | - -6. Click **Create**. - -Now you can proceed to deploy the web application. - -### Step 4: Deploy the web application - -To deploy the web application component, follow the steps below: - -1. In the left menu, click **Deploy**. -2. In the **Build Area** card, click **Deploy Manually**. The deployment may take a few minutes to complete. -3. Once the web application is deployed, copy the **Web App URL** from the development environment card. -4. Navigate to the web app URL. You can verify that the web app is successfully hosted. - -That's it! You can use a user created in your IdP and invoke the service through your web application. diff --git a/en/docs/consuming-services/create-a-subscription.md b/en/docs/consuming-services/create-a-subscription.md deleted file mode 100644 index 944817ae3..000000000 --- a/en/docs/consuming-services/create-a-subscription.md +++ /dev/null @@ -1,20 +0,0 @@ - -You must subscribe to a published API to use it in your application. New API subscriptions cover all minor versions within the subscribed API’s major version. - -The subscription process is designed to ensure the secure authentication of API requests via application keys. Alternatively, you can generate credentials for an API without an explicit subscription to an application. However, this approach limits the capability to control advanced configurations such as access token expiry time, revoke token expiry time, ID token expiry time, and enabling access to the API without a secret. Generating keys in the API is recommended for testing or short-term usage but not for long-term production usage. - -To subscribe to an API via an application, follow the steps given below: - -1. Sign in to the [Choreo Developer Portal](https://devportal.choreo.dev). -2. In the Developer Portal header, click **Applications**. -3. On the **My Applications** page, click on the application with which you want to subscribe to an API. -4. In the left navigation menu, click **Subscriptions**. -5. In the **Subscription Management** pane that opens, click **+ Add APIs**. -6. Click **Add** to subscribe to an API. Depending on your requirement, you can subscribe to one or more APIs. - - !!! tip - When a new minor version of an API is published, the major version-based invocation URL will automatically route to the latest minor version within the subscribed API's major version. This ensures that existing client applications can continue to function without disruption while benefiting from the improvements or additions in the newer minor version. - - ![Add APIs](../assets/img/consume/add-apis.png) - - Once you subscribe to an API, you can invoke the API using the application keys. diff --git a/en/docs/consuming-services/create-an-application.md b/en/docs/consuming-services/create-an-application.md deleted file mode 100644 index ab8750529..000000000 --- a/en/docs/consuming-services/create-an-application.md +++ /dev/null @@ -1,51 +0,0 @@ -An application in Choreo is a logical representation of a physical application such as a mobile app, web app, device, etc. To consume an API in Choreo, you need to create an application that maps to your physical application and then subscribes to the required API over a usage policy plan that gives you a usage quota. A single application can have multiple subscriptions to APIs. Using the consumer key and consumer secret, you can generate an access token that you can use to invoke all the APIs subscribed to the same application. - -This section walks you through the steps to create an application in Choreo. - -Let's get started! - -### Step 1: Create an application - -To create an application in the Choreo Developer Portal, follow the steps given below: - -1. Sign in to the [Choreo Developer Portal](https://devportal.choreo.dev). -2. Click **Applications**. and then click **+Create**. -3. Enter a name and description for the application. -4. Click **Create**. - -This creates the application and opens the application overview page. You can view details such as the token type, workflow status, and the application owner of the API. - -### Step 2: Generate keys - -Choreo provides an OAuth 2.0 bearer token-based authentication for API access. An API access token/key is a string that is passed as an HTTP header of an API request to authenticate access to the API. - -Once you create an application in Choreo, you can generate credentials for it. When you generate credentials for the first time, Choreo provides a consumer key and consumer secret for the application. The consumer key becomes the unique identifier of the application and is used to authenticate the application. - -The following section walks you through the steps to generate an API access token in Choreo. - -#### Generate environment-specific keys and tokens - -You can generate keys and tokens to invoke production and non-production endpoints separately. - -!!! info "Note" - The capability to access production endpoints depends on your role. If you have permission to access production endpoints, you can generate keys and tokens to invoke production endpoints. - -1. In the [Choreo Developer Portal](https://devportal.choreo.dev) header, click **Applications**. -2. On the **My Applications** page, click on the application for which you want to generate keys and tokens. -3. In the left navigation menu, click the required environment under **Credentials**. This opens the **Application Keys** pane of the specific environment. -4. Click to expand **Advanced Configurations** and review the options. - - **Grant Types**: Select the grant types to use when generating the access token. - - **Public Client**: Select **Allow authentication without the client secret** if your application can be considered as a public client such as an application running on a browser or mobile device. - - **PKCE for enhanced security**: Select **Mandatory** if you want the application to send a code challenge in the authorization request and the corresponding code verifier in the token request. Asgardeo supports SHA-256 and plain. - - **Application access token expiry time**: Specify the access token expiry time in seconds. - - **Refresh token expiry time**: Specify the refresh token expiry time in seconds. - - **ID token expiry time**: Specify the ID token expiry time in seconds. - -5. Click **Generate Credentials**. This opens the **Application Keys** pane with values populated for the credentials. - -You can use this consumer key and consumer secret values to generate an API access token by invoking the token endpoint. You can also revoke the access token by invoking the revoke endpoint. - -To generate a test token for testing purposes, you can click **Generate Token** and copy the test token that is displayed. Alternatively, click **cURL** and copy the generated cURL command to use via a cURL client and obtain a test token. - -!!! warning - Make sure you do not use the test token in your production environment. \ No newline at end of file diff --git a/en/docs/consuming-services/generate-an-access-token.md b/en/docs/consuming-services/generate-an-access-token.md deleted file mode 100644 index b9d0d5c8d..000000000 --- a/en/docs/consuming-services/generate-an-access-token.md +++ /dev/null @@ -1,43 +0,0 @@ -# Generate an Access Token - -Using access tokens for request authorization strengthens security measures, particularly in preventing certain types of denial-of-service (DoS) attacks aimed at published APIs. API consumers generate access tokens to access the API, incorporating them into their HTTP header requests as simple string values. - -When you register an application on the Developer Portal, you can generate a consumer key and a consumer secret for it. The consumer key and the consumer secret represent the credentials of the application. Similar to a user's username, the consumer key becomes the unique identifier of the application so that you can use it to authenticate the request to the API. Choreo issues an access token for the application against the mentioned consumer key. - -This section walks you through the steps to generate an access token for your application in Choreo. - -Let's get started! - -## Prerequisites - -Before you try out this guide, be sure you have the following: - -1. An application in the [Choreo Developer Portal](https://devportal.choreo.dev). If you do not have an application created, [create a new application](https://wso2.com/choreo/docs/consuming-services/manage-application/#step-1-create-an-application) -2. [Generate keys for the application](https://wso2.com/choreo/docs/consuming-services/create-an-application/#step-2-generate-keys). -3. [Subscribe APIs to the application](https://wso2.com/choreo/docs/consuming-services/create-a-subscription/#manage-subscriptions). - - -## Generate an access token via cURL - -You can follow the steps below to generate an access token for your application via cURL: - -1. In the [Choreo Developer Portal](https://devportal.choreo.dev) header, click **Applications**. -2. On the **My Applications** page, click on the application for which you want to generate the token. -3. In the left navigation menu, click the required environment under **Credentials**. This opens the **Application Keys** pane of the specific environment. -4. Copy the **Consumer Key**, **Consumer Secret**, and **Token Endpoint** values. -5. Use the following template and compile the cURL command with the values you copied in the above step. - - === "Format" - ``` - curl -k -X POST -d "grant_type=client_credentials" -H "Authorization: Basic " - ``` -6. Execute the cURL command to generate an access token. - -## Generate an access token via the Choreo Console (for testing purposes) - -You can follow the steps below to generate an access token for **testing purposes**: - -1. In the [Choreo Developer Portal](https://devportal.choreo.dev) header, click **Applications**. -2. On the **My Applications** page, click on the application for which you want to generate keys and tokens. -3. In the left navigation menu, click the required environment under **Credentials**. This opens the **Application Keys** pane of the specific environment. -4. Click **Generate Token**. \ No newline at end of file diff --git a/en/docs/consuming-services/manage-application.md b/en/docs/consuming-services/manage-application.md deleted file mode 100644 index bd0993918..000000000 --- a/en/docs/consuming-services/manage-application.md +++ /dev/null @@ -1,51 +0,0 @@ -# Manage Applications - -{% include "create-an-application.md" %} - -## Grant types - -Choreo authentication is based on OAuth 2.0. In OAuth 2.0, grant types are methods that allow client applications to obtain an access token depending on the type of the resource owner, the type of the application, and the trust relationship between the authorization server and the resource owner. - -### Authorization code grant - -The Authorization code flow provides a secure way for a client application to obtain an access token without exposing the user's credentials to the client application. The user only authenticates with the authorization server, which then issues an authorization code that can be exchanged for an access token. - -This helps to protect user credentials and prevents credentials from being compromised by malicious client applications. - -### Refresh token grant - -A refresh token is a token that you can use to get a new access token when your current access token is expired or when you need a new access token. You can use the refresh token grant type for this purpose. Issuing a refresh token is optional for the authorization server. If the authorization server issues a refresh token, it includes it in the response with the access token. You can use this refresh token and send it to the authorization server to obtain a new access token. Choreo's default authorization server, Asgardeo, issues refresh tokens for all grant types other than the **client credentials** grant type, as recommended by the OAuth 2.0 specification. - -!!! note - - - Keep your refresh token private, similar to the access token. - - The process to get a new access token using the Refresh Token grant type requires no user interaction. - -### Client credentials grant - -The client credentials flow provides a secure way for client applications to obtain an access token without user authentication. This is useful in scenarios where the client application needs to access its own resources, such as data storage or APIs, but does not require access to user data. However, it is important to ensure that the client credentials are kept secure because any party who has these credentials can obtain access tokens and access the client's resources. - -### Implicit grant - -The implicit grant flow is an OAuth 2.0 grant type that enables a client application to obtain an access token directly from the authorization server without an intermediate authorization code exchange. This flow is commonly used in browser-based applications where the client application runs in a web browser. - -However, it is important to note that the access token is exposed in the browser's URL fragment, which can make it vulnerable to certain types of attacks, such as cross-site scripting (XSS). As a result, this flow is typically not recommended for applications that require high security. - -### Password grant - -The password grant flow is an OAuth 2.0 grant type that enables a client application to obtain an access token by presenting the user's username and password directly to the authorization server. This flow is generally considered less secure than other grant types, as it requires the client application to handle and transmit the user's credentials. - -The password grant is primarily used in scenarios where the client application is highly trusted, and the user experience is prioritized over security concerns. It is generally not recommended for use in public-facing applications or scenarios where sensitive data is accessed. - - -## Revoke access tokens - -Revoking JWT access tokens can be challenging due to their self-validating nature. Once a token is issued, it contains all the necessary information within itself to validate its authenticity, without requiring additional server-side lookups or interactions. - -It is recommended to use an expiry time that is not more than 900 seconds. - -In traditional session-based authentication, the server can easily revoke a session by invalidating its associated session ID. However, in the case of JWTs, there is no central authority that maintains a list of valid or invalid tokens. As a result, revoking a JWT token requires the use of denylist or allowlist techniques, which can add additional complexity to the authentication flow and may not always be foolproof. - -To mitigate these challenges, it is recommended to use short-lived JWT access tokens and regularly refresh them. This reduces the risk of unauthorized access if a token is stolen or leaked, as the token will expire after a short period of time. Additionally, implementing other security measures such as strong encryption and secure token storage can further enhance the security of JWT-based authentication. - -The Choreo Developer Portal keeps the lifespan of a token to 15 minutes (900 seconds) by default. Application Developers can increase the time if necessary, but as mentioned above, it is recommended to keep it to the minimal possible value. diff --git a/en/docs/consuming-services/share-applications.md b/en/docs/consuming-services/share-applications.md deleted file mode 100644 index 7c4402b63..000000000 --- a/en/docs/consuming-services/share-applications.md +++ /dev/null @@ -1,17 +0,0 @@ -# Share Applications - -Choreo's application-sharing feature allows you to share your applications with members within your organization. This facilitates collaborative efforts when there is a need for multiple members to work on the same application. - -Follow the steps given below to share an application with members of your organization: - -1. Sign in to the [Choreo Developer Portal](https://devportal.choreo.dev/) and click the **Applications** tab. -2. On the **Applications** page, click on the application you want to share. -3. On the **Application Overview** page that opens, click the **Share** button displayed on the right side. -4. In the **Share Application** dialog, enter one or more email addresses depending on the members with whom you want to share the applications. - - !!! note - You must type an email address and press enter for it to get added. - -5. Click **Confirm**. This will share the application in read-only mode with the specified members. - - To see the members with whom the application is shared, go to the **Application Overview** page and take a look at the email addresses in the **Shared with** field. diff --git a/en/docs/develop-components/develop-a-webhook.md b/en/docs/develop-components/develop-a-webhook.md deleted file mode 100644 index 9f14afeee..000000000 --- a/en/docs/develop-components/develop-a-webhook.md +++ /dev/null @@ -1,157 +0,0 @@ -# Develop a Webhook - -Choreo allows developers to design high-quality webhooks. To explore this capability, let's consider a scenario where a team of software engineers in an organization should be notified via email whenever someone creates a GitHub issue with the `bug` label in a specific repository. - -In this tutorial, you will address the requirement by doing the following: - -- Create a webhook by connecting to a forked GitHub repository where you have the webhook implementation that addresses the described requirement. -- Deploy the webhook to the development environment. -- Modify the webhook implementation to connect the webhook to GitHub, enabling it to act in response to selected GitHub-related events. -- Test the webhook. -- Promote the webhook to the production environment. - -## Prerequisites - -Before you try out the steps in this guide, complete the following: - - - If you are signing in to the Choreo Console for the first time, create an organization as follows: - 1. Go to [https://console.choreo.dev/](https://console.choreo.dev/), and sign in using your preferred method. - 2. Enter a unique organization name. For example, `Stark Industries`. - 3. Read and accept the privacy policy and terms of use. - 4. Click **Create**. - This creates the organization and opens the **Project Home** page of the default project created for you. - - - Fork the [Choreo samples repository](https://github.com/wso2/choreo-samples), which contains the sample integration for this guide. - -## Step 1: Create a Webhook component - -To create a project, add a Webhook component to it, design the webhook, test it, and then commit it to make it available in the Choreo Console, follow these sub-steps: - -First, let's create a Webhook component as follows: - -1. Go to [https://console.choreo.dev/](https://console.choreo.dev/), and sign in using your preferred method. -2. If you already have one or more components in your project, click **+ Create**. Otherwise, proceed to the next step. -3. Go to the **Webhook** card and click **Create**. -4. This opens the **Create a Webhook** pane, where you can specify a name and description for the component. Enter a unique name and description. -5. Go to the **GitHub** tab. -6. To allow Choreo to connect to your GitHub account, click **Authorize with GitHub**. If you have not already connected your GitHub repository to Choreo, enter your GitHub credentials and select the repository you created in the prerequisites section to install the [Choreo GitHub App](https://github.com/marketplace/choreo-apps). - - Alternatively, you can paste the [Choreo samples repository](https://github.com/wso2/choreo-samples) URL in the **Provide Repository URL** field to connect to it without requiring authorization from the [Choreo Apps](https://github.com/marketplace/choreo-apps) GitHub application. However, authorizing the repository with the [Choreo GitHub App](https://github.com/marketplace/choreo-apps) is necessary if you want to enable [**Auto Deploy**](https://wso2.com/choreo/docs/choreo-concepts/ci-cd/#deploy) for the component. - - !!! note - The **Choreo GitHub App** requires the following permissions: - - - Read and write access to code and pull requests. - - Read access to issues and metadata. - - You can [revoke access](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/reviewing-your-authorized-integrations#reviewing-your-authorized-github-apps) if you do not want Choreo to have access to your GitHub account. However, write access is exclusively utilized for sending pull requests to a user repository. Choreo will not directly push any changes to a repository. - -7. Select the **Access Mode** depending on your requirement. -8. Enter the following information: - - | **Field** | **Description** | - |-------------------------------|--------------------| - | **GitHub Account** | Your account | - | **GitHub Repository** | choreo-samples | - | **Branch** | **`main`** | - | **Buildpack** | Ballerina | - | **Project Path** | `github-event-to-email-webhook`| - -9. Click **Create**. - -Choreo creates the Webhook component with the sample implementation and opens the component **Overview** page. - -## Step 2: Deploy - -Let's deploy the webhook to the development environment to make it invokable: - -1. In the Choreo Console left navigation menu, click **Deploy**. -2. In the **Build Area** card, click **Configure & Deploy**. -3. In the **Configurations** pane, enter the following information: - - 1. In the **webhookSecret** field, enter any value. - - !!! note - You must save this value for later use. - - 2. In the **toEmail** field, enter the email address to send notification emails. - 3. Click **Deploy**. - - You can monitor the deployment progress in the **Console** pane that opens on the right of the page. - -Once Choreo completes the deployment, the **Development** card indicates the **Deployment Status** as **Active**. - -!!! notes - In the deployment card, you can click the icon corresponding to configurables to open the **Configurations** pane and edit configurations: - - -## Step 3: Connect the webhook to the GitHub repository - -To allow the webhook to read the labels of issues in a specific GitHub repository, you must connect the webhook to the GitHub repository. To do this, follow these steps: - -1. In the Choreo Console left navigation menu, click **Overview**. - -2. On the **Overview** page, copy the invoke URL. You can click the copy icon within the **URL** field. - -3. Go to your GitHub account and open the repository for which you want to generate notification emails. - -4. In the top menu, click the **Settings** tab. - -5. In the left navigation menu, click **Webhooks**. - -6. Click **Add webhook** and enter the following information: - - | **Field** | **Value** | - |------------------|--------------------------------------------------------------------| - | **Payload URL** | The invoke URL you copied in Step 3, sub-step 1. | - | **Content Type** | Select `application/json` | - | **Secret** | The last webhook secret you configured in [Step 2](#step-2-deploy).| - - !!! tip - - **Buildpack** specifies the type of build to run depending on the implementation of the component. It converts the integration code into a Docker image that can run on Choreo cloud. If an integration is developed using [WSO2 Integration Studio](https://wso2.com/integration/integration-studio/), select **Micro Integrator** as the buildpack. If an integration is developed using the [Ballerina language](https://ballerina.io), select **Ballerina** as the buildpack. - - - **Project Path** specifies the location of the project to build the component. - -7. Under **Which events would you like to trigger this webhook?**, select **Let me select individual events**. - -8. Select the **Issues** checkbox in the list of events displayed. - - By doing so, you select GitHub issues as events that need to trigger this webhook. - -9. In the same list of events, clear the **Pushes** checkbox to ensure that GitHub does not trigger your webhook when the team pushes changes to the selected GitHub repository. - -10. Click **Add webhook** to save the configuration. - -Now you have integrated Choreo with GitHub via the webhook you created and deployed. You can proceed to test the webhook. - -## Step 4: Test - -To test your webhook, create a GitHub issue with the `Bug` label in the repository that you connected to the webhook. - -You will receive a mail similar to the following to the email address you provided in [Step 2](#step-2-deploy). - -## Step 5: Promote - -To promote the webhook to the Production environment, follow these steps: - -1. On the **Deploy** page, go to the **Development** card and click **Promote**. - -2. In the **Configuration Types** pane, leave the default selection (i.e., **Use default configuration values**) unchanged. - - If you have configured any default values for the configurable variables, selecting **Use default configuration values** allows you to proceed with those values. - - If you have not configured any default values for configurable variables, follow the steps given below to specify values. - -3. Click **Next**. - -4. In the **webhookSecret** field, enter any value. - - !!! note - You must save this value for later use. - -5. In the **toEmail** field, enter the email address to send notification emails. -6. Click **Promote**. - - Once the component is promoted to production, the **Production** card displays the deployment status as **Active**. - -Now you have successfully created, deployed, and tested a Webhook component and promoted it to production. diff --git a/en/docs/develop-components/develop-an-api-proxy.md b/en/docs/develop-components/develop-an-api-proxy.md deleted file mode 100644 index caf13c897..000000000 --- a/en/docs/develop-components/develop-an-api-proxy.md +++ /dev/null @@ -1,168 +0,0 @@ -# Develop an API Proxy - -An API proxy acts as an intermediary between an existing API and Choreo, intercepting all requests made to the API. It also functions as a managed API, which allows you to apply essential API management features such as security policies and rate limiting. - -In this guide, you will: - - - Create an API proxy component to expose an existing API. - - Deploy the API proxy. - - Test the API proxy to verify its functionality. - - Manage the API. - - Consume the API. - -## Prerequisites - -Before you try out this guide, complete the following: - -- If you are signing in to the Choreo Console for the first time, create an organization as follows: - - 1. Go to [https://console.choreo.dev/](https://console.choreo.dev/), and sign in using your preferred method. - 2. Enter a unique organization name. For example, `Stark Industries`. - 3. Read and accept the privacy policy and terms of use. - 4. Click **Create**. - - This creates the organization and opens the **Project Home** page of the default project created for you. - -## Step 1: Create an API proxy - -To create an API proxy, you can either upload an OpenAPI specification or provide an OpenAPI specification URL. In this guide, you will specify a URL to an OpenAPI definition of a sample API. - -Follow the steps given below: - -1. Go to [https://console.choreo.dev/](https://console.choreo.dev/) and sign in. This opens the project home page. -2. If you already have one or more components in your project, click **+ Create**. Otherwise, proceed to the next step. -3. Click the **API Proxy** card. - This opens the **Create an API Proxy** pane, where you can upload an OpenAPI definition or provide the URL of an OpenAPI. In this guide, you will define resources manually. Therefore, click **Skip Source** to proceed. -4. Specify the values given in the following table as API proxy details: - - !!! info - In the **Name** field, you must specify a name to uniquely identify the component in various contexts. The value is editable only at the time you create the component. You cannot change the name after you create the component. - - | **Field** | **Value** | - |------------------|--------------------------------------------| - | **Display Name** | `HR API` | - | **Name** | `hr-api` | - | **Context** | `abc-hr` | - | **Version** | `1.0` | - | **Target** | `https://samples.choreoapps.dev/company/hr`| - | **Access Mode** | **External** | - -5. Click **Create**. - - This creates the API proxy component and takes you to the **Overview** page. Now you can proceed to define resources for the API proxy. - -## Step 2: Define resources for the API proxy - -To add a new resource that can retrieve a department by the department ID, follow the steps given below: - -1. In the left navigation menu, click **Develop** and then click **Resources**. -2. Select **GET** as the **HTTP Verb** and enter `/department/{departmentId}` as the **URI Pattern**. -3. Click **+** to add the resource. -4. Click to expand the added resource and specify appropriate values for the **Operation ID** and **Description** fields. You can specify the values given in the following table: - - | **Field** | **Value** | - |------------------|--------------------------------------| - | **Operation ID** | `findDepartment` | - | **Description** | `Find a department by department ID` | - - 5. To remove the five default resources that start with `/*`, click the delete icon corresponding to each resource. This marks the resources for deletion. - 6. Click **Save**. - -## Step 3: Deploy the API proxy - -To deploy the API proxy to the development environment, follow the steps given below: - -1. In the left navigation menu, click **Deploy**. - -2. In the **Build Area** card, click **Configure & Deploy**. This opens the **Configure & Deploy** pane, where you can select the API access mode depending on how you want the API to be accessible. Here, you can select **External**. - -3. Click **Deploy**. The **Development** card indicates the **Deployment Status** as **Active** when the API proxy is successfully deployed. - -Now you are ready to test the API proxy. - -## Step 3: Test the API proxy - -Choreo allows you to test your API proxy using either the [integrated OpenAPI Console](../testing/test-rest-endpoints-via-the-openapi-console.md) or [cURL](../testing/test-apis-with-curl.md). - -In this guide, you will use the OpenAPI Console to test the API proxy. - -Follow the steps given below: - -!!! tip - Choreo enables OAuth 2.0 to secure APIs by default. Therefore, you need an access token to invoke an API. - - - Choreo automatically generates a key to test the API via the OpenAPI Console. To view the key, click the show key icon in the **Security Header** field. - - Choreo allows you to disable security for an entire API or a specific API resource for testing purposes. If you want to disable security, follow these steps: - 1. In the left navigation menu, click **Deploy**. - 2. Go to the **Build Area** card and click **Security Settings**. - 3. In the **Security Settings** pane, perform one of the following actions depending on your requirement: - - To disable security for the entire API, clear the **OAuth2** checkbox. - - To disable security for a specific API resource, go to the **Permissions** section, click to expand the relevant resource and then turn off the **Security** toggle. - 4. Click **Apply**. - - -1. In the left navigation menu, click **Test** and then click **OpenAPI Console**. - -2. Select **Development** from the environment drop-down list. - -3. Expand the `GET /department/{departmentId}` resource and click **Try it Out** to test it. - -4. Enter `1` as the **departmentId** and click **Execute**. You will see a response similar to the following: - - ![API proxy response](../assets/img/develop-components/develop-a-rest-api-proxy/rest-api-proxy-response.png){.cInlineImage-full} - - This indicates that your API proxy is working as expected. - -## Step 4: Manage the API proxy - -Now that you have a tested API proxy, you can publish it and make it available for application developers to consume. Depending on your requirement, you can apply security, throttling, and other settings to the API before you publish it. - -In this guide, you will apply rate limiting to the API and publish it. - -### Step 4.1: Apply a rate limiting level to the API proxy - -To apply a rate limiting level to the API, follow the steps given below: - -1. In the left navigation menu, click **Deploy**. -2. Go to the required environment card and click the setting icon corresponding to **API Configuration**. -3. In the **API Configuration** pane that opens, click **Rate Limiting** to expand the section. -4. Select **API Level** as the **Rate Limiting Level**. -5. Specify appropriate values for the **Request Limit** and **Time Unit** fields. In this guide, you can proceed with the default values. - This applies a rate-limiting policy to the entire API. If necessary, you can also apply rate limits at the operation level. For more information, see [API Rate Limiting](../api-management/api-rate-limiting.md). -6. Click **Apply**. This applies the rate limiting level to the API proxy and redeploys it. - -### Step 4.2: Publish the API proxy - -To publish the API proxy to the Choreo Developer Portal, follow the steps given below: - -1. In the left navigation menu, click **Lifecycle** under **Manage**. This takes you to the **Lifecycle** page where you can see the different lifecycle stages the API can be in. You can see that the current lifecycle stage is **Created**. -2. Click **Publish**. -3. In the **Publish API** dialog that opens, click **Confirm** to proceed publishing the API with the specified display name. If you want to change the display name, make the necessary changes and then click **Confirm**. This changes the API lifecycle state to **Published**. - -## Step 5: Invoke the API - -To generate credentials for the published API and to invoke it via the Choreo Developer Portal, follow the steps below: - -1. To open the published API in the Choreo Developer Portal via the **Lifecycle** page, click **Go to Devportal**. This takes you to the `HR API` in the Choreo Developer Portal. - -2. To generate credentials to test the API, follow the steps given below: - - 1. In the Developer Portal left navigation menu, click **Production** under **Credentials**. - 2. Click **Generate Credentials**. Choreo generates new tokens and populates the **Consumer Key** and **Consumer Secret** fields. - - !!! tip - If you want to test the API via an API test tool or through code, click **Generate Access Token** and copy the test token that is displayed. Alternatively, click **cURL** and copy the generated cURL command to use via a cURL client. You do not need to generate an access token if you are testing the API via the **Try Out** capability in the Choreo Developer Portal. - -3. To invoke a resource via the **Try Out** capability in the Choreo Developer Portal, follow the steps given below: - - 1. In the Developer Portal left navigation menu, click **Try Out**. - 2. In the **Endpoint** list, select **Development** as the environment to try out the API. - 3. To generate an access token to try out the API, click **Get Test Key**. This populates the **Access Token** field with a test key. - 4. Expand the `GET /department/{departmentId}` resource and click **Try it out**. - 5. Enter `1` as the **departmentId** and click **Execute**. You will see a response similar to the following: - - ![Try out response](../assets/img/develop-components/develop-a-rest-api-proxy/try-out-response.png){.cInlineImage-full} - -Now, you have gained hands-on experience creating, deploying, testing, and publishing an API proxy using Choreo API Manager. - -To learn more about the API management capabilities supported by Choreo API Manager, see [API Management](../api-management/lifecycle-management.md). diff --git a/en/docs/develop-components/develop-integrations/develop-a-manual-task.md b/en/docs/develop-components/develop-integrations/develop-a-manual-task.md deleted file mode 100644 index 01b8a2928..000000000 --- a/en/docs/develop-components/develop-integrations/develop-a-manual-task.md +++ /dev/null @@ -1,236 +0,0 @@ -# Develop a Manual Task - -This guide walks you through the steps to develop, deploy, test, and observe a manual task using Choreo. - -In this guide, you will: - - - Develop a manual task to fetch the weather forecast for a specified location for the next 24 hours from the [OpenWeatherMap](https://openweathermap.org) API. - - Process the weather data to a specific format. - - Send the formatted data to a specified email address. - -## Prerequisites - -Before you try out the steps in this guide, complete the following: - - - If you are signing in to the Choreo Console for the first time, create an organization as follows: - 1. Go to [https://console.choreo.dev/](https://console.choreo.dev/), and sign in. - 2. Enter a unique organization name. For example, `Stark Industries`. - 3. Read and accept the privacy policy and terms of use. - 4. Click **Create**. - This creates the organization and opens the **Project Home** page of the default project created for you. - - - Fork the [Choreo samples repository](https://github.com/wso2/choreo-samples), which contains the sample integration for this guide. - - !!! info "Repository file structure" - - To work with the sample repository, it is important to familiarize yourself with the repository file structure. The sample code for this guide is in the `/weather-to-email-integration` directory. To understand how the functionality is implemented, you must read the code comments. The following table describes what you will find in each file in the repository: - - | **File path** | **File content** | - | --------------------- | -------------------------------------------------------------------- | - | **Ballerina.toml** | Contains metadata about the project | - | **Dependencies.toml** | Lists the dependencies required for the project | - | **main.bal** | Contains the entry point of the project, including the main function | - | **types.bal** | Contains custom data types used in the project | - | **utils.bal** | Contains utility functions and helper functions used in the project | - - - Go to [OpenWeatherMap](https://openweathermap.org/) and sign up to obtain an API key. For details on how to obtain an API key, see the [OpenWeatherMap documentation](https://openweathermap.org/appid#signup). - - -## Step 1: Create a manual task component - -1. Go to [https://console.choreo.dev/](https://console.choreo.dev/) and sign in. This opens the project home page. -2. If you already have one or more components in your project, click **+ Create**. Otherwise, proceed to the next step. -3. Click the **Manual Task** card. -4. Enter a unique name and a description for the component. You can use the name and description given below: - - | **Field** | **Value** | - | ------------------ | -------------------------------- | - | **Component Name** | `WeatherToEmail` | - | **Description** | `My first manual task` | - -5. Go to the **GitHub** tab. -6. To allow Choreo to connect to your GitHub account, click **Authorize with GitHub**. If you have not already connected your GitHub repository to Choreo, enter your GitHub credentials and select the repository you created in the prerequisites section to install the [Choreo GitHub App](https://github.com/marketplace/choreo-apps). - - Alternatively, you can paste the [Choreo samples repository](https://github.com/wso2/choreo-samples) URL in the **Provide Repository URL** field to connect to it without requiring authorization from the [Choreo Apps](https://github.com/marketplace/choreo-apps) GitHub application. However, authorizing the repository with the [Choreo GitHub App](https://github.com/marketplace/choreo-apps) is necessary if you want to enable [**Auto Deploy**](https://wso2.com/choreo/docs/choreo-concepts/ci-cd/#deploy) for the component. - - !!! note - The **Choreo GitHub App** requires the following permissions: - - - Read and write access to code and pull requests. - - Read access to issues and metadata. - - You can [revoke access](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/reviewing-your-authorized-integrations#reviewing-your-authorized-github-apps) if you do not want Choreo to have access to your GitHub account. However, write access is exclusively utilized for sending pull requests to a user repository. Choreo will not directly push any changes to a repository. - -7. Enter the following information: - - | **Field** | **Description** | - | ----------------------| -----------------------------------------------------| - | **Organization** | Your GitHub account | - | **Repository** | `choreo-samples` | - | **Branch** | **`main`** | - | **Buildpack** | **Ballerina** | - | **Project Directory** | `weather-to-email-integration`| - - !!! tip - - **Buildpack** specifies the type of build to run depending on the implementation of the component. It converts the integration code into a Docker image that can run on Choreo cloud. If an integration is developed using [WSO2 Integration Studio](https://wso2.com/integration/integration-studio/), select **Micro Integrator** as the buildpack. If an integration is developed using the [Ballerina language](https://ballerina.io), select **Ballerina** as the buildpack. - - - **Project Directory** specifies the location of the project to build the component. - -8. Click **Create**. Choreo initializes the component with the sample implementation and opens the **Overview** page of the component. - -## Step 2: Build the manual task - -To build the manual task, follow the steps given below: - -1. In the left navigation menu, click **Build**. -2. In the **Builds** pane, click **Build**. This opens the **Commits** pane where you can see all the commits related to the component. -3. Select the latest commit and click **Build**. This triggers the build process and displays the build progress in the **Build Logs** pane. - - !!! info - The build process can take a while to complete. When the build process is complete, the build will be listed in the **Builds** pane along with the build status. - - Here, you will see the build status as **Success**. - -## Step 3: Deploy the manual task - -To deploy the manual task, follow the steps given below: - -1. In the left navigation menu, click **Deploy**. -2. In the **Set Up** card, click **Configure & Deploy**. -3. In the **Configurations** pane, specify values as follows for the configurable variables: - - !!! tip - The configurable variables populated here are defined in the sample Ballerina project used in this guide. To learn how to declare configurable variables in Ballerina, see the [Ballerina documentation on declaring configurable variables](https://ballerina.io/learn/by-example/configurable-variables/). If configurable variables are detected in a connected Ballerina project, Choreo prompts for the respective values during component deployment. - - | **Field** | **Value** | - | ------------- | ----------------------------------------------------------------------- | - | **apiKey** | The API key you obtained in the prerequisites section | - | **latitude** | Latitude of the location to get the weather forecast | - | **longitude** | Longitude of the location to get the weather forecast | - | **email** | The email address to receive the formatted weather forecast information | - - !!! note - If you use **Ballerina** as the buildpack and you want to set a configurable variable as a secret, click the lock icon corresponding to the configurable variable. This marks it as a secret and conceals the input value. - - For example, if you consider the configurable variables in this guide and set the **apiKey** as a secret, its input value will be concealed as follows: - - ![Configurable variable as a secret](../../assets/img/develop-components/develop-a-scheduled-integration/configurable-variable-as-a-secret.png) - - If you want to update the input value at a later time, you can click **Update Secret Content** and specify a new value. - - ![Update secret](../../assets/img/develop-components/develop-a-scheduled-integration/update-secret.png) - -4. Click **Deploy**. - -## Step 4: Execute the manual task - -To execute the manual task, follow the steps given below: - -1. In the left navigation menu, click **Execute**. -2. Click **Run Now**. This triggers the task. - - !!! info "Inject dynamic values into your application as command-line arguments" - If you want to inject dynamic values into your application as command-line arguments when you run a manual task, follow the steps given below: - - 1. Click the drop-down icon next to **Run Now** and then click **Run with Arguments**. - 2. In the **Runtime Arguments** pane that opens, enter the arguments you want to pass to your application. - 3. Click **Execute**. This triggers the task with the specified arguments. - - The capability to run a manual task with arguments is supported for the following buildpacks: - - === "Dockerfile" - - To explore a Dockerfile-based manual task with arguments, try out the [Hello World Task](https://github.com/wso2/choreo-samples/tree/main/docker-hello-world-manual-task) sample. For instructions, see the `readme.md` file in the sample repository. - - !!! info - When you work on Docker projects, the **Run with Arguments** capability is not supported if the Dockerfile contains `CMD`. In such scenarios, you must use `ENTRYPOINT` to define your default commands. - - === "Go" - - To explore a Go-based manual task with arguments, try out the [Hello World Go Task](https://github.com/wso2/choreo-samples/tree/main/hello-world-go-task) sample. For instructions, see the `readme.md` file in the sample repository. - - === "Java" - - To explore a Java-based manual task with arguments, try out the [Hello World Java Task](https://github.com/wso2/choreo-samples/tree/main/hello-world-java-task) sample. For instructions, see the `readme.md` file in the sample repository. - - !!! info - When you work on Java projects: - - - The **Run with Arguments** capability is not supported if `Procfile` is available in the project. - - The `Main` class should be defined in the `manifest` file. - - If Maven files such as `mvn.cmd` exist in the project without the `.mvn` directory, the build will fail. To ensure a successful build, you must either commit the `.mvn` directory along with any Maven files or not include any Maven files in the project if you choose not to commit the `.mvn` directory. - - === "NodeJS" - - To explore a NodeJS-based manual task with arguments, try out the [Hello World NodeJS Task](https://github.com/wso2/choreo-samples/tree/main/hello-world-nodejs-task) sample. For instructions, see the `readme.md` file in the sample repository. - - !!! info - When you work on NodeJS projects: - - - The **Run with Arguments** capability is not supported if `Procfile` is available in the project. - - The project root must contain the `package.json` file with the `main` attribute defined. - - === "WSO2 MI" - - To explore a WSO2 MI-based manual task with arguments, try out the [Weather to Logs Task](https://github.com/wso2/choreo-samples/tree/main/weather-to-logs-mi-manual-task) sample. For instructions, see the `readme.md` file in the sample repository. - - !!! info - When you work on WSO2 MI projects and you want to deploy a WSO2 MI integration as a manual task in Choroeo, you must use the WSO2 MI automation mode. For details, see [Running the Micro Integrator in Automation Mode](https://apim.docs.wso2.com/en/latest/install-and-setup/install/running-the-mi-in-automation-mode/). - - === "Ballerina" - - To explore a Ballerina manual task with arguments, try out the [Weather to Email Task](https://github.com/wso2/choreo-samples/tree/main/weather-to-email-integration) sample. For instructions, see the README.md file in the sample repository. - - !!! info - If you want to pass arguments to Ballerina main functions, you can use the **Run with Arguments** capability. For details on the arguments you can pass, see the [Ballerina documentation](https://ballerina.io/learn/by-example/main-function/). You can also override configurable values in the same manner. For more information, see [Provide values to configurable variables](https://ballerina.io/learn/provide-values-to-configurable-variables/#provide-via-command-line-arguments). - - -## Step 5: Test the manual task - -Once the task is triggered, an email with the subject `[WSO2 Choreo Demo] Next 24H Weather Forecast` is sent from `choreo.demo@gmail.com` to the email address specified as the **email** configurable variable value in [Step 3](#step-3-deploy-the-manual-task). - -If the manual task ran successfully, you should receive an email similar to the following to the email address you specified: - -![Received email](../../assets/img/develop-components/develop-a-scheduled-integration/Received-email.png) - -## Step 6: Observe the manual task - -The observability view in Choreo displays graphs that depict details such as throughput, latency, diagnostic data, and logs to identify and troubleshoot anomalies in components you deploy. - -To visualize and monitor the performance of the manual task you deployed, click **Observability** in the left navigation menu. You can observe the following: - - - The throughput and latencies of requests served over a given period. - - The logs that are generated over a given period. - - The flame graph (Diagnostics View) that is generated over a given period. - - The low-code diagram. - -To learn more about the observability details you can view via Choreo observability, see [Observability Overview](../../monitoring-and-insights/observability-overview.md). - -## Step 7: Monitor executions - -To track and monitor executions associated with the deployed scheduled task, go to the left navigation menu and click **Execute**. - -!!! tip - The **Execute** view is applicable to both scheduled and manual tasks. - -You can view the following information: - -- The total number of executions within the past 30 days. - - ![Total Execution](../../assets/img/develop-components/develop-a-scheduled-integration/total_executions.png) - -- The currently active executions and those that are already complete. - - Here, you can view information such as the execution ID, the revision of the execution, and the time it was triggered. - - ![Execution History](../../assets/img/develop-components/develop-a-scheduled-integration/execution_history.png) - -- Detailed execution logs for a specific execution. - - You can click on an execution to view detailed logs related to it. - - !!! info - - It may take a few minutes for the logs to appear. You may need to manually refresh to view the latest logs. - - ![Execution History](../../assets/img/develop-components/develop-a-scheduled-integration/execution_logs.png) diff --git a/en/docs/develop-components/develop-integrations/develop-a-scheduled-task.md b/en/docs/develop-components/develop-integrations/develop-a-scheduled-task.md deleted file mode 100644 index 3a3a270ad..000000000 --- a/en/docs/develop-components/develop-integrations/develop-a-scheduled-task.md +++ /dev/null @@ -1,195 +0,0 @@ -# Develop a Scheduled Task - -Choreo is a versatile integration platform that allows you to create various types of integrations depending on your requirement. - -If you have a requirement to automatically run a specific integration at regular intervals, you can use Choreo to develop a scheduled task. This type of integration can automate the synchronization of data between different systems at specified intervals, reducing errors and improving productivity by eliminating the need for manual intervention. - -This guide walks you through the steps to develop, deploy, test, and observe a scheduled task using Choreo. - -In this guide, you will: - - - Develop a scheduled task to fetch the weather forecast for a specified location for the next 24 hours from the [OpenWeatherMap](https://openweathermap.org) API. - - Process the weather data to a specific format. - - Send the formatted data to a specified email address at a specific time every day. - -## Prerequisites - -Before you try out the steps in this guide, complete the following: - - - If you are signing in to the Choreo Console for the first time, create an organization as follows: - 1. Go to [https://console.choreo.dev/](https://console.choreo.dev/), and sign in using your preferred method. - 2. Enter a unique organization name. For example, `Stark Industries`. - 3. Read and accept the privacy policy and terms of use. - 4. Click **Create**. - This creates the organization and opens the **Project Home** page of the default project created for you. - - - Fork the [Choreo samples repository](https://github.com/wso2/choreo-samples), which contains the sample integration for this guide. - - !!! info "Repository file structure" - - To work with the sample repository, it is important to familiarize yourself with the repository file structure. The sample code for this guide is in the `/weather-to-email-scheduled-task` directory. To understand how the functionality is implemented, you must read the code comments. The following table describes what you will find in each file in the repository: - - | **File path** | **File content** | - | --------------------- | -------------------------------------------------------------------- | - | **Ballerina.toml** | Contains metadata about the project | - | **Dependencies.toml** | Lists the dependencies required for the project | - | **main.bal** | Contains the entry point of the project, including the main function | - | **types.bal** | Contains custom data types used in the project | - | **utils.bal** | Contains utility functions and helper functions used in the project | - - - Go to [OpenWeatherMap](https://openweathermap.org/) and sign up to obtain an API key. For details on how to obtain an API key, see the [OpenWeatherMap documentation](https://openweathermap.org/appid#signup). - - -## Step 1: Create a scheduled task component - -1. Go to [https://console.choreo.dev/](https://console.choreo.dev/) and sign in. This opens the project home page. -2. If you already have one or more components in your project, click **+ Create**. Otherwise, proceed to the next step. -3. Click the **Scheduled Task** card. -4. Enter a unique name and a description for the component. You can use the name and description given below: - - | **Field** | **Value** | - | ------------------ | -------------------------------- | - | **Component Name** | `WeatherToEmail` | - | **Description** | `My first scheduled task` | - -5. Go to the **GitHub** tab. -6. To allow Choreo to connect to your GitHub account, click **Authorize with GitHub**. If you have not already connected your GitHub repository to Choreo, enter your GitHub credentials and select the repository you created in the prerequisites section to install the [Choreo GitHub App](https://github.com/marketplace/choreo-apps). - - Alternatively, you can paste the [Choreo samples repository](https://github.com/wso2/choreo-samples) URL in the **Provide Repository URL** field to connect to it without requiring authorization from the [Choreo Apps](https://github.com/marketplace/choreo-apps) GitHub application. However, authorizing the repository with the [Choreo GitHub App](https://github.com/marketplace/choreo-apps) is necessary if you want to enable [**Auto Deploy**](https://wso2.com/choreo/docs/choreo-concepts/ci-cd/#deploy) for the component. - - !!! note - The **Choreo GitHub App** requires the following permissions: - - - Read and write access to code and pull requests. - - Read access to issues and metadata. - - You can [revoke access](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/reviewing-your-authorized-integrations#reviewing-your-authorized-github-apps) if you do not want Choreo to have access to your GitHub account. However, write access is exclusively utilized for sending pull requests to a user repository. Choreo will not directly push any changes to a repository. - -7. Enter the following information: - - | **Field** | **Description** | - | --------------------- | ---------------------------------------------- | - | **Organization** | Your GitHub account | - | **Repository** | `choreo-samples` | - | **Branch** | **`main`** | - | **Buildpack** | **Ballerina** | - | **Project Directory** | `weather-to-email-scheduled-task` | - - !!! tip - - **Buildpack** specifies the type of build to run depending on the implementation of the component. It converts the integration code into a Docker image that can run on Choreo cloud. If an integration is developed using [WSO2 Integration Studio](https://wso2.com/integration/integration-studio/), select **Micro Integrator** as the buildpack. If an integration is developed using the [Ballerina language](https://ballerina.io), select **Ballerina** as the buildpack. - - - **Project Directory** specifies the location of the project to build the component. - -8. Click **Create**. Choreo initializes the component with the sample implementation and opens the **Overview** page of the component. - -Now you can proceed to build and deploy the scheduled task. - -## Step 2: Build the scheduled task - -To build the scheduled task, follow the steps given below: - -1. In the left navigation menu, click **Build**. -2. In the **Builds** pane, click **Build**. This opens the **Commits** pane where you can see all the commits related to the component. -3. Select the latest commit and click **Build**. This triggers the build process and displays the build progress in the **Build Logs** pane. - - !!! info - The build process can take a while to complete. When the build process is complete, the build will be listed in the **Builds** pane along with the build status. - - Here, you will see the build status as **Success**. - -## Step 3: Deploy the scheduled task - -To deploy the scheduled task, follow the steps given below: - -1. In the left navigation menu, click **Deploy**. -2. In the **Set Up** card, click **Configure & Deploy**. -3. In the **Configurations** pane, specify values as follows for the configurable variables: - - !!! tip - The configurable variables populated here are defined in the sample Ballerina project used in this guide. To learn how to declare configurable variables in Ballerina, see the [Ballerina documentation on declaring configurable variables](https://ballerina.io/learn/by-example/configurable-variables/). If configurable variables are detected in a connected Ballerina project, Choreo prompts for the respective values during component deployment. - - - | **Field** | **Value** | - | ------------- | ----------------------------------------------------------------------- | - | **apiKey** | The API key you obtained in the prerequisites section | - | **latitude** | Latitude of the location to get the weather forecast | - | **longitude** | Longitude of the location to get the weather forecast | - | **email** | The email address to receive the formatted weather forecast information | - - !!! note - If you use **Ballerina** as the buildpack and you want to set a configurable variable as a secret, click the lock icon corresponding to the configurable variable. This marks it as a secret and conceals the input value. - - For example, if you consider the configurable variables in this guide and set the **apiKey** as a secret, its input value will be concealed as follows: - - ![Configurable variable as a secret](../../assets/img/develop-components/develop-a-scheduled-integration/configurable-variable-as-a-secret.png) - - If you want to update the input value at a later time, you can click **Update Secret Content** and specify a new value. - - ![Update secret](../../assets/img/develop-components/develop-a-scheduled-integration/update-secret.png) - -4. Click **Next**. -5. In this step, you must define a schedule to run the task. In this guide, you set the schedule to receive the weather information daily at 8.00 AM UTC. Enter values as follows to configure the schedule: - - | **Field** | **Value** | - | -------------------- | ----------------------------------------------------- | - | **Select Time Zone** | Select a time zone to schedule the task | - | **Select Range** | **Day** | - | **Every** | `1` | - | **At** | `08:00` | - - !!! tip - When you develop a scheduled task, you can define a schedule depending on your requirement. If you want to test and verify the immediately, you can schedule the deployment to run in just a few minutes after you create it. However, to avoid unnecessary expenses, make sure you reschedule or stop the deployment once you test and verify. - -6. Click **Deploy**. This deploys the scheduled task to the development environment and indicates the **Scheduled Status** as **Active** in the **Development** card. - - You can test the scheduled task when it runs at the configured time. - -## Step 4: Test the scheduled task - -When the scheduled task runs at the configured time, an email with the subject `[WSO2 Choreo Demo] Next 24H Weather Forecast` is sent from `choreo.demo@gmail.com` to the email address specified as the **email** configurable variable value in [Step 3](#step-3-deploy-the-scheduled-task). - -If the scheduled task ran successfully, you should receive an email similar to the following to the email address you specified: - -![Received email](../../assets/img/develop-components/develop-a-scheduled-integration/Received-email.png) - -## Step 5: Observe the scheduled task - -The observability view in Choreo displays graphs that depict details such as throughput, latency, diagnostic data, and logs to identify and troubleshoot anomalies in components you deploy. - -To visualize and monitor the performance of the scheduled task you deployed, click **Observability** in the left navigation menu. You can observe the following: - - - The throughput and latencies of requests served over a given period. - - The logs that are generated over a given period. - - The flame graph (Diagnostics View) that is generated over a given period. - - The low-code diagram. - -To learn more about the observability details you can view via Choreo observability, see [Observability Overview](../../monitoring-and-insights/observability-overview.md). - -## Step 6: Monitor executions - -To track and monitor executions associated with the deployed scheduled task, go to the left navigation menu and click **Execute**. - -!!! tip - The **Execute** view is applicable to both scheduled and manual tasks. - -You can view the following information: - -- The total number of executions within the past 30 days. - - ![Total Execution](../../assets/img/develop-components/develop-a-scheduled-integration/total_executions.png) - -- The currently active executions and those that are already complete. - - Here, you can view information such as the execution ID, the revision of the execution, and the time it was triggered. - - ![Execution History](../../assets/img/develop-components/develop-a-scheduled-integration/execution_history.png) - -- Detailed execution logs for a specific execution. - - You can click on an execution to view detailed logs related to it. - - !!! info - - It may take a few minutes for the logs to appear. You may need to manually refresh to view the latest logs. - - ![Execution History](../../assets/img/develop-components/develop-a-scheduled-integration/execution_logs.png) diff --git a/en/docs/develop-components/develop-integrations/develop-an-event-handler.md b/en/docs/develop-components/develop-integrations/develop-an-event-handler.md deleted file mode 100644 index 26602acee..000000000 --- a/en/docs/develop-components/develop-integrations/develop-an-event-handler.md +++ /dev/null @@ -1,106 +0,0 @@ -# Develop an Event Handler - -An Event Handler executes predefined actions in response to specific events. Choreo simplifies the process of creating and deploying such integrations. - -This guide walks you through the steps to create and deploy an Event Handler using WSO2 MI and Choreo. - -In this guide, you will build a simple event handler that monitors RabbitMQ for new messages and displays them once they become available. - -## Prerequisites - -Before you try out the steps in this guide, complete the following: - - - If you are signing in to the Choreo Console for the first time, create an organization as follows: - 1. Go to [https://console.choreo.dev/](https://console.choreo.dev/), and sign in using your preferred method. - 2. Enter a unique organization name. For example, `Stark Industries`. - 3. Read and accept the privacy policy and terms of use. - 4. Click **Create**. - This creates the organization and opens the **Project Home** page of the default project created for you. - - - Use an existing RabbitMQ instance or start a new [RabbitMQ](https://www.rabbitmq.com/download.html) instance on a server that can be accessed via the internet. Obtain the `username`, `hostname`, `password`, and `vhost` from the RabbitMQ instance to use later as environment variables. - - - Fork the [Choreo samples repository](https://github.com/wso2/choreo-samples), which contains the sample integration for this guide. - -## Step 1: Create an event handler component - -1. Go to [https://console.choreo.dev/](https://console.choreo.dev/) and sign in. This opens the project home page. -2. If you already have one or more components in your project, click **+ Create**. Otherwise, proceed to the next step. -3. Click the **Event Handler** card. -4. Enter a unique name and a description for the component. You can use the name and description given below: - - | **Field** | **Value** | - |--------------------|------------------------| - | **Component Name** | `SalesOrderListener` | - | **Description** | `RabbitMQ integration` | - -5. Go to the **GitHub** tab. -6. To allow Choreo to connect to your GitHub account, click **Authorize with GitHub**. If you have not already connected your GitHub repository to Choreo, enter your GitHub credentials and select the repository you created in the prerequisites section to install the [Choreo GitHub App](https://github.com/marketplace/choreo-apps). - - Alternatively, you can paste the [Choreo samples repository](https://github.com/wso2/choreo-samples) URL in the **Provide Repository URL** field to connect to it without requiring authorization from the [Choreo Apps](https://github.com/marketplace/choreo-apps) GitHub application. However, authorizing the repository with the [Choreo GitHub App](https://github.com/marketplace/choreo-apps) is necessary if you want to enable [**Auto Deploy**](https://wso2.com/choreo/docs/choreo-concepts/ci-cd/#deploy) for the component. - - !!! note - The **Choreo GitHub App** requires the following permissions: - - - Read and write access to code and pull requests. - - Read access to issues and metadata. - - You can [revoke access](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/reviewing-your-authorized-integrations#reviewing-your-authorized-github-apps) if you do not want Choreo to have access to your GitHub account. However, write access is exclusively utilized for sending pull requests to a user repository. Choreo will not directly push any changes to a repository. - -7. Enter the following information: - - | **Field** | **Description** | - |-----------------------|----------------------------- | - | **Organization** | Your GitHub account | - | **Repository** | `choreo-samples` | - | **Branch** | **`main`** | - | **Buildpack** | **WSO2 MI** because you are creating the REST API from a [WSO2 Integration Studio](https://wso2.com/micro-integrator/) project| - | **Project Directory** | `mi-rabbitmq-listener` | | - - !!! tip - - **Buildpack** specifies the type of build to run depending on the implementation of the component. It converts the integration code into a Docker image that can run on Choreo cloud. If an integration is developed using [WSO2 Integration Studio](https://wso2.com/integration/integration-studio/), select **Micro Integrator** as the buildpack. If an integration is developed using the [Ballerina language](https://ballerina.io), select **Ballerina** as the buildpack. - - - **Project Directory** specifies the location of the project to build the component. - -8. Click **Create**. - -## Step 2: Deploy the integration - -To deploy the integration, follow the steps given below: - -1. In the left navigation menu, click **Deploy**. -2. In the **Build Area** card, click **Configure & Deploy**. -3. In the **Configurations** pane, click **+ Add** corresponding to **Environment Variables** and add the following environment variables: - - !!! tip - Use the values from your RabbitMQ instance as per the [Prerequisites](#prerequisites) section, for the environment variables. - - | **Name** | **Value** | - | ------------- |--------------------------------------------------| - | **HOSTNAME** | Hostname of your RabbitMQ server | - | **VHOST** | Virtual hostname of your RabbitMQ server | - | **USERNAME** | Username for connecting to RabbitMQ | - | **PASSWORD** | Password associated with the RabbitMQ username | - -4. Click **Deploy**. This deploys the event handler to the development environment and indicates the **Deployment Status** as **Active** in the **Development** card. - - -## Step 3: Test the integration - -To test the integration, follow the steps given below: - -1. Send a sales order message to the **SalesOrderQueue** on the RabbitMQ server. - - You can send a sample sales order message similar to the following: - ```json - { - "order_id": "12345", - "customer_name": "John Doe", - "product": "Widget", - "quantity": 10, - "total_amount": 100.00 - } - ``` -2. Observe the logs: - - In the left navigation menu, click **Logs** and then click **Runtime Logs**. You will see the order message in the logs. - -Now you have gained hands-on experience in creating, configuring, and deploying an event handler. - diff --git a/en/docs/develop-components/develop-integrations/develop-an-integration-with-integration-studio.md b/en/docs/develop-components/develop-integrations/develop-an-integration-with-integration-studio.md deleted file mode 100644 index d6c8683e3..000000000 --- a/en/docs/develop-components/develop-integrations/develop-an-integration-with-integration-studio.md +++ /dev/null @@ -1,118 +0,0 @@ -# Develop an Integration with Integration Studio - -The seamless integration of APIs, microservices, applications, and data across different languages and formats requires the ability to expose integrations as APIs. Choreo simplifies building, deploying, and managing integration components, making it easy for you to quickly expose integrations as APIs. - -!!! note - - To develop integrations that you need to use in Manual Task and Schedule Task components in Choreo, you need to use the automation mode in the WSO2 Micro Integrator. See [Running MI in Automation Mode](https://apim.docs.wso2.com/en/4.2.0/install-and-setup/install/running-the-mi-in-automation-mode/). - - To develop integrations for any other component types (Service, webhook, event-handler, etc) you need to use the server mode. - -This guide walks you through the steps to expose an integration you created in WSO2 Integration Studio as an API in Choreo. - -In this guide, you will: - - - Create a component to expose the sample integration in the [Choreo samples repository](https://github.com/wso2/choreo-samples) as an API. - - Deploy, test, and observe the integration component. - - Publish the integration component as an API to the Choreo Developer Portal. - -## Prerequisites - -Before you try out the steps in this guide, complete the following: - - - If you are signing in to the Choreo Console for the first time, create an organization as follows: - 1. Go to [https://console.choreo.dev/](https://console.choreo.dev/), and sign in using your preferred method. - 2. Enter a unique organization name. For example, `Stark Industries`. - 3. Read and accept the privacy policy and terms of use. - 4. Click **Create**. - This creates the organization and opens the **Project Home** page of the default project created for you. - - - Fork the [Choreo samples repository](https://github.com/wso2/choreo-samples), which contains the sample integration for this guide. - -## Step 1: Create the integration component - -1. Go to [https://console.choreo.dev/](https://console.choreo.dev/) and sign in. This opens the project home page. -2. If you already have one or more components in your project, click **+ Create**. Otherwise, proceed to the next step. -3. Click the **Service** card. -4. Enter a unique name and a description for the component. You can enter the name and description given below: - - | **Field** | **Value** | - |--------------------|------------------------| - | **Component Name** | `Hello World` | - | **Description** | `Hello World REST API` | - -5. Go to the **GitHub** tab. -6. To allow Choreo to connect to your GitHub account, click **Authorize with GitHub**. If you have not already connected your GitHub repository to Choreo, enter your GitHub credentials and select the repository you created in the prerequisites section to install the [Choreo GitHub App](https://github.com/marketplace/choreo-apps). - - Alternatively, you can paste the [Choreo samples repository](https://github.com/wso2/choreo-samples) URL in the **Provide Repository URL** field to connect to it without requiring authorization from the [Choreo Apps](https://github.com/marketplace/choreo-apps) GitHub application. However, authorizing the repository with the [Choreo GitHub App](https://github.com/marketplace/choreo-apps) is necessary if you want to enable [**Auto Deploy**](https://wso2.com/choreo/docs/choreo-concepts/ci-cd/#deploy) for the component. - - !!! note - The **Choreo GitHub App** requires the following permissions: - - - Read and write access to code and pull requests. - - Read access to issues and metadata. - - You can [revoke access](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/reviewing-your-authorized-integrations#reviewing-your-authorized-github-apps) if you do not want Choreo to have access to your GitHub account. However, write access is exclusively utilized for sending pull requests to a user repository. Choreo will not directly push any changes to a repository. - -7. Enter the following information: - - | **Field** | **Description** | - |-----------------------|----------------------------- | - | **Organization** | Your GitHub account | - | **Repository** | `choreo-samples` | - | **Branch** | **`main`** | - | **Buildpack** | **WSO2 MI** because you are creating the REST API from a [WSO2 Integration Studio](https://wso2.com/micro-integrator/) project| - | **Project Directory** | `hello-world-mi` | - -8. Click **Create**. Choreo initializes the component with the sample integration. - -## Step 2: Deploy the integration component - -To deploy the integration component to the development environment, follow the steps given below: - -1. In the Choreo Console left navigation menu, click **Deploy**. -2. In the **Build Area** card, click **Configure & Deploy**. -3. In the **Configurations** pane, click **Next**. This displays details of the endpoint ready to be deployed. -4. Click **Deploy**. This deploys the integration component to the development environment. -The **Development** card indicates the **Deployment Status** as **Active** when the integration is successfully deployed. - - !!! tip - Choreo uses [endpoints](../../choreo-concepts/endpoint.md) to expose **Service** component to the network. You can read more about configuring endpoints in [Configure Endoints](../configure-endpoints.md). - - !!! tip - Automatic deployment is enabled for the component by default. Therefore, you are required to perform only the first deployment manually. - -Now you can test the integration. - -## Step 3: Test the integration - -To test the integration using the OpenAPI Console. Follow the steps given below: - -1. In the Choreo Console left navigation menu, click **Test** and then click **Console**. -2. In the OpenAPI Console that opens, select **Development** from the environment drop-down list. -3. Click to expand the **GET /integration** operation. -4. Click **Try it out** and then click **Execute**. This sends a request to your deployed integration. -5. Go to the **Response body** section and observe the response returned by the integration. If the integration works as expected, you should see a response similar to the following: - - `{"Hello" : "Integration"}` - -## Step 4: Observe the integration - -The observability view in Choreo displays graphs that depict details such as throughput, latency, diagnostic data, and logs to identify and troubleshoot anomalies in components you deploy. - -To visualize and monitor the performance of the integration component you deployed, click **Observability** in the left navigation menu. You can observe the following: - - - The throughput and latencies of requests served over a given period. - - The logs that are generated over a given period. - - The flame graph (Diagnostics View) that is generated over a given period. - -To learn more about the observability details you can view via Choreo observability, see [Observability Overview](../../monitoring-and-insights/observability-overview.md). - -## Step 5: Publish the integration component - -To publish the integration component, follow the steps given below: - -1. In the Choreo Console left navigation menu, click **Manage** and then click **Lifecycle**. This opens the **Lifecycle Management** pane, where you can see the different lifecycle stages that an API can be in. You can see that the current lifecycle stage is **Created**. -2. In the **Lifecycle Management** pane, click **Publish**. This changes the API lifecycle stage to **Published** and exposes the integration as an API in the Choreo Developer Portal. - - To open the published API in the Developer Portal via the **Lifecycle Management** pane, click **Go to Devportal**. In the Choreo Developer Portal, you can view the published API, manage subscriptions for it, and generate access tokens for testing purposes. - -Now, you have gained hands-on experience in exposing an integration designed using WSO2 Integration Studio as a REST API in Choreo. diff --git a/en/docs/develop-components/develop-services/develop-a-ballerina-service.md b/en/docs/develop-components/develop-services/develop-a-ballerina-service.md deleted file mode 100644 index e29314997..000000000 --- a/en/docs/develop-components/develop-services/develop-a-ballerina-service.md +++ /dev/null @@ -1,137 +0,0 @@ -# Develop a Ballerina Service - -Choreo allows you to develop and deploy applications using your preferred programming language. This guide demonstrates how to deploy a service component that exposes a REST API using the [Ballerina language](https://ballerina.io/). No prior knowledge of the Ballerina language is required to follow this guide. - -A REST API is a web service adhering to Representational State Transfer (REST) principles, using HTTP methods to access and manage resources. This guide walks you through building a Ballerina service component, deploying it on Choreo, and using it with an HTTP client application. - -In this guide, you will: - -- Build a simple greeting service using a sample service implementation. The sample implementation will have a single resource named `greet` that accepts a single query parameter as input. - - Request: - - `$ curl GET http://localhost:9090/greeter/greet?name=Ballerina` - - - Response: - - `$ hello Ballerina!` - -- Deploy the service in Choreo. The service will run on port 9090. -- Test the service. - -## Prerequisites - -Before you try out this guide, complete the following: - -- If you are signing in to the Choreo Console for the first time, create an organization as follows: - - 1. Go to [https://console.choreo.dev/](https://console.choreo.dev/), and sign in using your preferred method. - 2. Enter a unique organization name. For example, `Stark Industries`. - 3. Read and accept the privacy policy and terms of use. - 4. Click **Create**. - - This creates the organization and opens the **Project Home** page of the default project created for you. - -- Fork the [Choreo samples repository](https://github.com/wso2/choreo-samples/), which contains the [sample greetings service](https://github.com/wso2/choreo-samples/tree/main/greeting-service) implementation in `Ballerina`. - - -### Learn the repository file structure - -It is important to understand the purpose of the key files in the sample service. The following table provides a brief overview of each file in the greeter service: - -!!! note - The specified file paths are relative to `/greeting-service`. - -|**Filepath** |**Description** | -|--------------------------|---------------------------------------------------------------| -| `service.bal` | The greetings service code written in the Ballerina language. | -| `tests/service_test.bal` | Test files related to the `service.bal` file. | -| `Ballerina.toml` | The Ballerina configuration file. | - -Let's get started! - -## Step 1: Create a service component - -To create a Ballerina service component, follow these steps: - -1. Go to [https://console.choreo.dev/](https://console.choreo.dev/) and sign in. This opens the project home page. -2. If you already have one or more components in your project, click **+ Create**. Otherwise, proceed to the next step. -3. Click the **Service** card. -4. Enter a display name, a unique name, and a description for the service component. You can enter the values given below: - - !!! info - In the **Component Name** field, you must specify a name to uniquely identify the component in various contexts. The value is editable only at the time you create the component. You cannot change the name after you create the component. - - | **Field** | **Value** | - |---------------------------|-------------------------| - | **Component Display Name**| `Ballerina Greetings` | - | **Component Name** | `ballerina-greetings` | - | **Description** | Send greetings | - -5. Go to the **GitHub** tab. -6. To allow Choreo to connect to your GitHub account, click **Authorize with GitHub**. If you have not already connected your GitHub repository to Choreo, enter your GitHub credentials and select the repository you created in the prerequisites section to install the [Choreo GitHub App](https://github.com/marketplace/choreo-apps). - - Alternatively, you can paste the [Choreo samples repository](https://github.com/wso2/choreo-samples) URL in the **Provide Repository URL** field to connect to it without requiring authorization from the [Choreo Apps](https://github.com/marketplace/choreo-apps) GitHub application. However, authorizing the repository with the [Choreo GitHub App](https://github.com/marketplace/choreo-apps) is necessary if you want to enable [**Auto Deploy**](https://wso2.com/choreo/docs/choreo-concepts/ci-cd/#deploy) for the component. - - !!! note - The **Choreo GitHub App** requires the following permissions: - - - Read and write access to code and pull requests. - - Read access to issues and metadata. - - You can [revoke access](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/reviewing-your-authorized-integrations#reviewing-your-authorized-github-apps) if you do not want Choreo to have access to your GitHub account. However, write access is exclusively utilized for sending pull requests to a user repository. Choreo will not directly push any changes to a repository. - -7. Under **Connect Your Repository**, enter the following information: - - | **Field** | **Value** | - |------------------------|--------------------| - | **Organization** | Your GitHub account| - | **Repository** | choreo-samples | - | **Branch** | **`main`** | - -8. Select **Ballerina** as the buildpack. -9. In the **Ballerina Project Directory**, specify `/greeting-service`. -10. Click **Create**. This creates the component and takes you to the **Overview** page of the component. - -You have successfully created a service that exposes a REST API written in the Ballerina language. Next, let's build and deploy the service. - -## Step 2: Build and deploy - -Now that you have connected the source repository and configured the endpoint details, it's time to build and deploy the service. - -!!! note - If you are rebuilding the Ballerina service component after changing the Ballerina version, ensure that before building the code, the version of the Ballerina distribution mentioned in the `Ballerina.toml` file matches the distribution version specified in the `Dependencies.toml` file. - -### Step 2.1: Build - -To build the service, follow these steps: - -1. In the left navigation menu, click **Build**. -2. On the **Build** page, click **Build Latest**. - - !!! note - Building the service component may take a while. You can track the progress via the logs in the **Build Details** pane. Once the build process is complete, the build status changes to **Success**. - - -### Step 2.2: Deploy - -To deploy the service, follow these steps: - -1. In the left navigation menu, click **Deploy**. -2. On the **Set Up** card, click **Configure & Deploy**. -3. In the **Configurations** pane that opens, click **Next** to skip the configuration. -4. Review the **Endpoint Details** and click **Deploy**. - - !!! note - Deploying the service component may take a while. Once deployed, the **Development** environment card indicates the **Deployment Status** as **Active**. -To build and deploy the service, follow the steps below: - -Once you have successfully deployed your service, you can test, manage, and observe it like any other component type in Choreo. - -For detailed instructions, see the following sections: - -- [Step 3: Test](../../testing/test-rest-endpoints-via-the-openapi-console.md) -- [Step 4: Manage](../../api-management/lifecycle-management.md) - -## Manage the deployment - -If you want to view Kubernetes-level insights to perform a more detailed diagnosis of this Ballerina REST API, see Choreo's [DevOps capabilities](../../devops-and-ci-cd/view-runtime-details.md). diff --git a/en/docs/develop-components/develop-services/develop-a-service-with-docker.md b/en/docs/develop-components/develop-services/develop-a-service-with-docker.md deleted file mode 100644 index 9ef5d2db6..000000000 --- a/en/docs/develop-components/develop-services/develop-a-service-with-docker.md +++ /dev/null @@ -1,152 +0,0 @@ -# Develop a Service with Docker - -Choreo is a platform that allows you to create and deploy applications in any language. - -In this guide, you will: - -- create a containerized service component using a sample service implementation. The sample implementation will have a single resource named `greet` that accepts a single query parameter as input. -- Deploy it in Choreo using a Dockerfile. The service will run on port 9090. -- Test the service. - -If you want to create a service component that exposes a Ballerina service, see [Develop a Ballerina Service ](develop-a-ballerina-service.md). - -## Prerequisites - -Before you try out this guide, complete the following: - -- If you are signing in to the Choreo Console for the first time, create an organization as follows: - - 1. Go to [https://console.choreo.dev/](https://console.choreo.dev/), and sign in using your preferred method. - 2. Enter a unique organization name. For example, `Stark Industries`. - 3. Read and accept the privacy policy and terms of use. - 4. Click **Create**. - - This creates the organization and opens the **Project Home** page of the default project created for you. - -- Fork the [Choreo samples repository](https://github.com/wso2/choreo-samples/), which contains the [sample greetings service](https://github.com/wso2/choreo-samples/tree/main/greeting-service-go) implementation with the Dockerfile. - - -### Learn the repository file structure - -It is important to understand the purpose of the key files in the sample service. The following table provides a brief overview of each file in the greeter service: - -!!! note - The specified file paths are relative to `/greeting-service-go` - -|**Filepath** |**Description** | -|---------------------------|------------------------------------------------------------------------------| -| `main.go` | The Go-based greeter service code. | -| `Dockerfile` | The Dockerfile to build the container image of the application. | -|`.choreo/component.yaml`  | Choreo-specific configuration that provides information about how Choreo exposes the service.| -| `openapi.yaml` | The OpenAPI contract of the greeter service. This is required to publish the service as a managed API. This `openapi.yaml` file is referenced by the `.choreo/component.yaml` file.| - -Let's get started! - -### Configure the service port with endpoints - -In Choreo, you can expose your services via endpoints. - -You are going to run the greeter service on port 9090. To securely expose the service through Choreo, you must provide the port and other required information to Choreo. For detailed information on each attribute of an endpoint, see [Configure Endpoints](../configure-endpoints.md). - -To configure the endpoint details of a containerized component, Choreo looks for an `component.yaml` file inside the `.choreo` directory. Be sure to place the `.choreo` directory at the root of the Docker build context path. - -In the greeter sample, the `component.yaml` file is in the `greeting-service-go/.choreo/` directory. - -## Step 1: Create a service component from a Dockerfile - -To create a containerized service component, follow these steps: - -1. Go to [https://console.choreo.dev/](https://console.choreo.dev/cloud-native-app-developer) and sign in. This opens the project home page. -2. If you already have one or more components in your project, click **+ Create**. Otherwise, proceed to the next step. -3. Click the **Service** card. -4. Enter a display name, a unique name, and a description for the service component. You can enter the values given below: - - !!! info - In the **Component Name** field, you must specify a name to uniquely identify the component in various contexts. The value is editable only at the time you create the component. You cannot change the name after you create the component. - - | **Field** | **Value** | - |---------------------------|--------------------| - | **Component Display Name**| `Greetings` | - | **Component Name** | `greetings` | - | **Description** | Send greetings | - -5. Go to the **GitHub** tab. -6. To allow Choreo to connect to your GitHub account, click **Authorize with GitHub**. If you have not already connected your GitHub repository to Choreo, enter your GitHub credentials and select the repository you created in the prerequisites section to install the [Choreo GitHub App](https://github.com/marketplace/choreo-apps). - - Alternatively, you can paste the [Choreo samples repository](https://github.com/wso2/choreo-samples) URL in the **Provide Repository URL** field to connect to it without requiring authorization from the [Choreo Apps](https://github.com/marketplace/choreo-apps) GitHub application. However, authorizing the repository with the [Choreo GitHub App](https://github.com/marketplace/choreo-apps) is necessary if you want to enable [**Auto Deploy**](https://wso2.com/choreo/docs/choreo-concepts/ci-cd/#deploy) for the component. - - !!! note - The **Choreo GitHub App** requires the following permissions: - - - Read and write access to code and pull requests. - - Read access to issues and metadata. - - You can [revoke access](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/reviewing-your-authorized-integrations#reviewing-your-authorized-github-apps) if you do not want Choreo to have access to your GitHub account. However, write access is exclusively utilized for sending pull requests to a user repository. Choreo will not directly push any changes to a repository. - -7. Under **Connect Your Repository**, enter the following information: - - | **Field** | **Value** | - |------------------------|--------------------| - | **Organization** | Your GitHub account| - | **Repository** | choreo-samples | - | **Branch** | **`main`** | - -8. Select **Docker** as the buildpack. -9. Enter the following information: - - | **Field** | **Value** | - |--------------------------|----------------------------------| - | **Docker Context** | `/greeting-service-go` | - | **Dockerfile** | `/greeting-service-go/Dockerfile`| - - !!! info - 1. To successfully build your container with Choreo, it is essential to explicitly define a user ID (UID) under the USER instruction in your Dockerfile. For reference, see [sample Dockerfile](https://github.com/wso2/choreo-sample-apps/blob/main/go/greeter/Dockerfile). - To ensure that the defined USER instruction is valid, it must conform to the following conditions: - - A valid User ID is a numeric value between 10000-20000, such as `10001` or `10500`. - - Usernames are considered invalid and should not be used. For example, `my-custom-user-12221` or `my-custom-user` are invalid User IDs. - - 2. The Dockerfile used in this guide is a multi-stage Dockerfile, which is designed to keep the final image size small and provides the ability to build the application with a specific version of tools and libraries. - -10. Click **Create**. This creates the component and takes you to the **Overview** page of the component. - -You have successfully created a service from a Dockerfile. Next, you can build and deploy the service. - -## Step 2: Build and deploy - -Now that we have connected the source repository, and configured the endpoint details, it's time to build the service and create an image. Then we can deploy that image test the greeter service. - -### Step 2.1: Build - -To build the service, follow these steps: - -1. In the left navigation menu, click **Build**. -2. On the **Build** page, click **Build Latest**. - - !!! note - Building the service component may take a while. You can track the progress via the logs in the **Build Details** pane. Once the build process is complete, the build status changes to **Success**. - - You can access the following scans under **Build**. - - - **The Dockerfile scan**: Choreo performs a scan to check if a non-root user ID is assigned to the Docker container to ensure security. If no non-root user is specified, the build will fail. - - **Container (Trivy) vulnerability scan**: This detects vulnerabilities in the final docker image. - - **Container (Trivy) vulnerability scan**: The details of the vulnerabilities open in a separate pane. If this scan detects critical vulnerabilities, the build will fail. - - !!! info - If you have Choreo environments on a private data plane, you can ignore these vulnerabilities and proceed with the deployment. - -### Step 2.2: Deploy - -To deploy the service, follow these steps: - -1. In the left navigation menu, click **Deploy**. -2. On the **Set Up** card, click **Configure & Deploy**. -3. In the **Environment Configurations** pane that opens, click **Next** to skip the configuration. -4. In the **File Mount** pane, click **Next** to skip the configuration. -5. Review the **Endpoint Details** and click **Deploy**. - - !!! note - Deploying the service component may take a while. Once deployed, the **Development** environment card indicates the **Deployment Status** as **Active**. - -Once you have successfully deployed the service, you can [test](../../testing/test-rest-endpoints-via-the-openapi-console.md), [manage](../../api-management/lifecycle-management.md), and [observe](../../monitoring-and-insights/observability-overview.md) it like any other component type in Choreo. - -To perform a more detailed diagnosis of this Dockerfile-based REST API by viewing Kubernetes-level insights, see [Choreo's DevOps capabilities](../../devops-and-ci-cd/view-runtime-details.md). diff --git a/en/docs/develop-components/develop-services/develop-a-service.md b/en/docs/develop-components/develop-services/develop-a-service.md deleted file mode 100644 index 242bea75a..000000000 --- a/en/docs/develop-components/develop-services/develop-a-service.md +++ /dev/null @@ -1,130 +0,0 @@ -# Develop a Service - -Choreo allows you to create and deploy applications in your preferred programming language. - -In this guide, you will: - -- Build a simple greeting service using a sample service implementation. The sample implementation will have a single resource named `greet` that accepts a single query parameter as input. -- Deploy the service in Choreo using a `Go` buildpack. The service will run on port 9090. -- Test the service. - -## Prerequisites - -Before you try out this guide, complete the following: - -- If you are signing in to the Choreo Console for the first time, create an organization as follows: - - 1. Go to [https://console.choreo.dev/](https://console.choreo.dev/), and sign in using your preferred method. - 2. Enter a unique organization name. For example, `Stark Industries`. - 3. Read and accept the privacy policy and terms of use. - 4. Click **Create**. - - This creates the organization and opens the **Project Home** page of the default project created for you. - -- Fork the [Choreo samples repository](https://github.com/wso2/choreo-samples/), which contains the [sample greetings service](https://github.com/wso2/choreo-samples/tree/main/greeting-service-go) implementation in `Go`. - -### Learn the repository file structure - -It is important to understand the purpose of the key files in the sample service. The following table provides a brief overview of each file in the greeter service: - -!!! note - The specified file paths are relative to `/greeting-service-go` - -|**Filepath** |**Description** | -|-------------------------|------------------------------------------------------------------------------| -| `main.go` | The Go-based greeter service code. | -| `.choreo/component.yaml`  | Choreo-specific configuration that provides information about how Choreo exposes the service.| -| `openapi.yaml` | The OpenAPI contract of the greeter service. This is required to publish the service as a managed API. This `openapi.yaml` file is referenced by the `.choreo/component.yaml` file.| - -Let's get started! - -### Configure the service port with endpoints - -In Choreo, you can expose your services via endpoints. - -You are going to run the greeter service on port 9090. To securely expose the service through Choreo, you must provide the port and other required information to Choreo. For detailed information on each attribute of an endpoint, see [Configure Endpoints](../configure-endpoints.md). - -To configure the endpoint details of a containerized component, Choreo looks for an `component.yaml` file inside the `.choreo` directory. Be sure to place the `.choreo` directory at the root of the Docker build context path. - -In the greeter sample, the `component.yaml` file is in the `greeting-service-go/.choreo/` directory. - -## Step 1: Create a service component - -To create a containerized service component, follow these steps: - -1. Go to [https://console.choreo.dev/](https://console.choreo.dev/) and sign in. This opens the project home page. -2. If you already have one or more components in your project, click **+ Create**. Otherwise, proceed to the next step. -3. Click the **Service** card. -4. Enter a display name, a unique name, and a description for the service component. You can enter the values given below: - - !!! info - In the **Component Name** field, you must specify a name to uniquely identify the component in various contexts. The value is editable only at the time you create the component. You cannot change the name after you create the component. - - | **Field** | **Value** | - |---------------------------|--------------------| - | **Component Display Name**| `Greetings` | - | **Component Name** | `greetings` | - | **Description** | Send greetings | - -5. Go to the **GitHub** tab. -6. To allow Choreo to connect to your GitHub account, click **Authorize with GitHub**. If you have not already connected your GitHub repository to Choreo, enter your GitHub credentials and select the repository you created in the prerequisites section to install the [Choreo GitHub App](https://github.com/marketplace/choreo-apps). - - Alternatively, you can paste the [Choreo samples repository](https://github.com/wso2/choreo-samples) URL in the **Provide Repository URL** field to connect to it without requiring authorization from the [Choreo Apps](https://github.com/marketplace/choreo-apps) GitHub application. However, authorizing the repository with the [Choreo GitHub App](https://github.com/marketplace/choreo-apps) is necessary if you want to enable [**Auto Deploy**](https://wso2.com/choreo/docs/choreo-concepts/ci-cd/#deploy) for the component. - - !!! note - The **Choreo GitHub App** requires the following permissions: - - - Read and write access to code and pull requests. - - Read access to issues and metadata. - - You can [revoke access](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/reviewing-your-authorized-integrations#reviewing-your-authorized-github-apps) if you do not want Choreo to have access to your GitHub account. However, write access is exclusively utilized for sending pull requests to a user repository. Choreo will not directly push any changes to a repository. - -7. Under **Connect Your Repository**, enter the following information: - - | **Field** | **Value** | - |------------------------|--------------------| - | **Organization** | Your GitHub account| - | **GitHub Repository** | choreo-samples | - | **Branch** | **`main`** | - -8. Select **Go** as the buildpack. -9. Enter the following information: - - | **Field** | **Value** | - |--------------------------|------------------------| - | **Go Project Directory** | `/greeting-service-go` | - | **Language Version** | 1.x | - -10. Click **Create**. This creates the component and lists it under **Component Listing** on the project home page. - -You have successfully created the service. The next step is to build and deploy it. - -## Step 2: Build and deploy - -Now that you have connected the source repository and configured the endpoint details, it's time to build and deploy the greeter service. - -### Step 2.1: Build - -To build the service, follow these steps: - -1. On the project home page, click on the `Greetings` component you created. This takes you to the component overview page. -2. In the left navigation menu, click **Build**. -3. On the **Build** page, click **Build Latest**. - - !!! note - Building the service component may take a while. You can track the progress via the logs in the **Build Details** pane. Once the build process is complete, the build status changes to **Success**. - -### Step 2.2: Deploy - -To deploy the service, follow these steps: - -1. In the left navigation menu, click **Deploy**. -2. On the **Set Up** card, click **Configure & Deploy**. -3. In the **Environment Configurations** pane that opens, click **Next** to skip the configuration. -4. In the **File Mount** pane, click **Next** to skip the configuration. -5. Review the **Endpoint Details** and click **Deploy**. - - !!! note - Deploying the service component may take a while. Once deployed, the **Development** environment card indicates the **Deployment Status** as **Active**. - -Once you have successfully deployed the service, you can [test](../../testing/test-rest-endpoints-via-the-openapi-console.md), [manage](../../api-management/lifecycle-management.md), and [observe](../../monitoring-and-insights/observability-overview.md) it like any other component type in Choreo. diff --git a/en/docs/develop-components/develop-web-applications/build-and-deploy-a-single-page-web-application.md b/en/docs/develop-components/develop-web-applications/build-and-deploy-a-single-page-web-application.md deleted file mode 100644 index de6fae50c..000000000 --- a/en/docs/develop-components/develop-web-applications/build-and-deploy-a-single-page-web-application.md +++ /dev/null @@ -1,214 +0,0 @@ -# Build and Deploy a Single-Page Web Application - -A web application is an application program hosted on a server and serves ingress traffic through a browser. In Choreo, you can deploy a web application by creating a Web Application component and connecting it to a Git repository that contains the implementation of the web application. Web applications can fall into one of the following categories: - -- **Single page applications (SPAs)**: Examples include React, Angular, Vue, Svelte, etc. -- **Web servers**: These serve static content or provide server-side rendering/static site generation (SSR/SSG). -- **Static content**: Examples include websites and other static resources that do not require a backend, usually comprising static HTML/JS/CSS files. - -## Prerequisites - -- To deploy a Web Application component, you must have a GitHub account with a repository containing the web application's implementation. For this guide, fork the [https://github.com/wso2/choreo-samples](https://github.com/wso2/choreo-samples) repository, which contains the sample web application implementation. - -## Create a web application - -You can create a web application in Choreo as follows: - -- Build and deploy a SPA from the source code. - - Create a Web Application component by connecting a repository that includes the web application source code. - - Select the relevant buildpack. Default buildpacks include **React**, **Angular**, and **Vue.js**. If you are using a different SPA framework, you can try one of these buildpacks because the configurations can be overridden to support most Javascript-based SPAs. - - Enter the build command based on your package manager. - NPM, yarn, and pnpm are supported and the relevant package manager is run based on the dependency lock file in your repository (defaults to NPM if no lock file is present). - - Specify the build output directory. - - Specify the NodeJS version. Choreo does not pick the Nodejs version from the `package.json` engine property. The required Node version must be explicitly set in the build configuration. - - Once you create the Web Application component, Choreo automatically generates a build pipeline for your single-page application and deploys it. - -- Bring your Dockerfile. - - Create a Web Application component by connecting a repository that contains the Dockerfile for your containerized web application. - - Commit a Dockerfile to your connected git repository to have full control over your build process. - - This approach is recommended if you are deploying a web server and not just a single-page application (or a single-page application with a complex build process). - -- Host static websites. - - To host static web content, you can create a Web Application component and connect it to the GitHub repository that contains the required static assets. - - Select the **Static Websites** buildpack. This buildpack does not trigger a build process. It only fetches the files from the path specified in the repository and serves as it is. - -Now let's take a look at how you can build and deploy a SPA from source code: - -Follow the steps below to create a sample Web Application component and deploy it in Choreo: - -1. Sign in to the Choreo Console at [https://console.choreo.dev/login/](https://console.choreo.dev/login/). This opens the **Project Home** page. -2. If you already have one or more components in your project, click **+ Create**. Otherwise, proceed to the next step. -3. Click the **Web Application** card. -4. This opens the **Create a Web Application** pane, where you can specify a name and description for the component. Enter a unique name and description. -5. Go to the **GitHub** tab. -6. To allow Choreo to connect to your GitHub account, click **Authorize with GitHub**. If you have not already connected your GitHub repository to Choreo, enter your GitHub credentials and select the repository you created in the prerequisites section to install the [Choreo GitHub App](https://github.com/marketplace/choreo-apps). - - Alternatively, you can paste the [Choreo samples repository](https://github.com/wso2/choreo-samples) URL in the **Provide Repository URL** field to connect to it without requiring authorization from the [Choreo Apps](https://github.com/marketplace/choreo-apps) GitHub application. However, authorizing the repository with the [Choreo GitHub App](https://github.com/marketplace/choreo-apps) is necessary if you want to enable [**Auto Deploy**](https://wso2.com/choreo/docs/choreo-concepts/ci-cd/#deploy) for the component. - - !!! note - The **Choreo GitHub App** requires the following permissions: - - - Read and write access to code and pull requests. - - Read access to issues and metadata. - - You can [revoke access](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/reviewing-your-authorized-integrations#reviewing-your-authorized-github-apps) if you do not want Choreo to have access to your GitHub account. However, write access is exclusively utilized for sending pull requests to a user repository. Choreo will not directly push any changes to a repository. - -7. Enter the following information: - - | **Field** | **Description** | - |---------------------------|------------------------| - | **GitHub Account** | Your account | - | **GitHub Repository** | choreo-samples | - | **Branch** | **main** | - -8. Select **React** as the **Buildpack**. -9. Enter the following information: - - | **Field** | **Description** | - |---------------------------|------------------------| - | **Project Directory** | /react-single-page-app | - | **Build Command** | `npm run build` | - | **Build Path** | `build` | - | **Node Version** | `18` | - - !!! tip - Managed authentication is enabled by default when you create a web application using **React**, **Angular**, or **Vue.js** buildpacks. To learn how to set up authentication for your web application with Choreo's managed authentication, see [Secure Web Applications with Managed Authentication](../../authentication-and-authorization/secure-web-applications-with-managed-authentication.md). - -10. Click **Create**. Choreo initializes the component with the sample implementation and opens the **Overview** page of the component. - -You have successfully created a Web Application component from the source code. Now let's build and deploy the web application. - -## Build your web application - -To build the web application, follow the steps given below: - -1. In the left navigation menu, click **Build**. -2. In the **Builds** pane, click **Build**. This opens the **Commits** pane, where you can see all the commits related to the component. -3. Select the latest commit and click **Build**. This triggers the build process and displays the progress in the **Build Logs** pane. - - You can access the following scans in the **Build Logs** pane: - - - **The Dockerfile scan**: Choreo performs a scan to check if a non-root user ID is assigned to the Docker container to ensure security. If no non-root user is specified, the build will fail. - - **Container (Trivy) vulnerability scan**: This detects vulnerabilities in the final docker image. - - **Container (Trivy) vulnerability scan**: The details of the vulnerabilities open in a separate pane. If this scan detects critical vulnerabilities, the build will fail. - - !!! info - If you have Choreo environments on a private data plane, you can ignore these vulnerabilities and proceed with the deployment. - - - !!! note - The build process can take a while to complete. When the build process is complete, the build will be listed in the **Builds** pane along with its status. - - Here, you will see the build status as **Success**. - -## Deploy and access your web application - -1. In the left navigation menu, click **Deploy**. -2. In the **Set Up** card, click **Configure and Deploy**. This opens the **Configure & Deploy** pane, where you can add a file mount if necessary. In this guide, you will not add a file mount. -3. Click **Next**. This takes you to the **Authentication Settings** pane. -4. Keep the default settings and click **Deploy**. - - !!! note - - The deployment process can take a few minutes to complete. On successful deployment, you will see the **Deployment Status** as **Active** in the **Development** card. - -5. To verify that you have successfully hosted the web application, click the **Web App URL** in the **Development** card. This takes you to the web application. - -## Create a short URL for your web application in production - -!!! info - This feature is only available on the Choreo cloud data plane. - -When you promote your component to the Production environment, you have the option to create a personalized short URL for your web application. The URL follows the `https://{your-short-prefix}.choreoapps.dev` structure, where you can select a name of your preference for `{your-short-prefix}`. - -To create a short URL for your web application, follow the steps given below: - -1. Click **Promote** in the **Development** card and promote your web application to production. -2. In the **Production** card, click **Create a short URL**. -3. Specify a **Short URL prefix** of your choice and click **Save**. - - !!! note - Short URL names/prefixes are subject to availability, provided on a first-come-first-serve basis. - -## Manage runtime configurations for web applications - -For web applications with a backend server, Choreo allows you to mount runtime configurations and secrets as environment variables and/or file mounts for a specific environment. Alternatively, you can also inject them into the client application during server-side rendering or when serving static content. - -However, in the case of SPAs that run completely on the browser, Choreo does not support *baking-in* environment variables or other configurations. This is because Choreo follows a multi-environment deployment model, where configuration should be kept separate from the build and injected at runtime. For example, in most React SPA frameworks, the `process.env` stub is available during build time. However, it does not actually read in variables from the runtime. Instead, it is baked into the final JavaScript output during the build process. - -To manage runtime configurations, Choreo recommends the following approach (although this is a React example, the approach is generally applicable to other SPA frameworks as well). - -!!! note - - With SPAs, anything you mount as a runtime config will be available to your users in the browser. - - **Do not include sensitive secrets that are not browser-safe**. - - -Follow the steps given below to manage runtime configurations for the React application you created above: - -1. Go to your forked [Choreo samples repository](https://github.com/wso2/choreo-samples). -2. Open the public directory. -3. Create and commit a new file named `config.js` in the public directory of your React application. This file should contain the runtime configuration variables you want to expose to your application, such as API endpoints or feature flags. Let's expose the API URL and a feature flag as follows: - - ``` - window.config = { - apiUrl: 'https://api.example.com', - featureFlags: { - enableNewFeature: true, - enableExperimentalFeature: false, - }, - }; - ``` -4. In your `index.html` file inside the public directory, add a script tag as follows to include the `config.js` file inside the tag. The `config.js` file will be accessible via JavaScript at runtime. - - ``` - - - - - My React App - - -
- - - - - ``` -This makes the `window.config` object available to your app at runtime. - -1. In your React component, you can access the configuration variables by referencing the `window.config` object as follows: - - ``` - import React from 'react'; - - function MyComponent() { - const apiUrl = window.config.apiUrl; - const enableNewFeature = window.config.featureFlags.enableNewFeature; - const enableExperimentalFeature = window.config.featureFlags.enableExperimentalFeature; - - // ... - } - ``` -Now you can deploy your component. - -2. When you deploy your component to Choreo, create a config file mount in the specified path for each environment (where your `index.html` expects the `config.js` file as in this example). -[https://wso2.com/choreo/docs/devops-and-ci-cd/manage-configurations-and-secrets/#apply-a-file-mount-to-your-container](https://wso2.com/choreo/docs/devops-and-ci-cd/manage-configurations-and-secrets/#apply-a-file-mount-to-your-container). - -## Limitations - -The following limitations are specific to the Choreo cloud data plane: - - - Request size limit, including headers, cookies, and payloads: 256KB - - Response body size limit: 20MB - - Only one open port is permitted per web application. While you can have multiple ports open for project-level communication within a data plane, incoming traffic from the internet can only be directed to one port. This differs from the Service type components, which support multiple endpoints. - -## Troubleshoot a web application - -- **I’m seeing a blank page or a 502 error after I deploy my web application** - - If you encounter a blank page or a 502 error after deploying your web application, it typically indicates that the wrong directory is being served. To resolve this issue, follow these steps: - - - Double-check the build output directory, especially if you are using a Dockerfile-less buildpack. Ensure that the specified output directory matches the actual output directory generated during the build process. For example, if you have erroneously entered `public/` as the output directory when it should have been `build/`. - - By verifying and correcting the output directory alignment, you should be able to address the issue of encountering a blank page or experiencing a 502 error on deploying your web application. diff --git a/en/docs/develop-components/develop-web-applications/develop-web-applications-locally-with-managed-authentication.md b/en/docs/develop-components/develop-web-applications/develop-web-applications-locally-with-managed-authentication.md deleted file mode 100644 index 1879613a0..000000000 --- a/en/docs/develop-components/develop-web-applications/develop-web-applications-locally-with-managed-authentication.md +++ /dev/null @@ -1,76 +0,0 @@ -# Develop Web Applications Locally with Choreo’s Managed Authentication - -Choreo’s managed authentication capability exposes a set of backend for frontend (BFF) endpoints, facilitating authentication and authorization for web applications. These endpoints are readily available for single-page web applications deployed on Choreo. - -As a web application developer, there may be instances where it becomes necessary to run the application on your personal workstation. In such situations, the expectation is for authentication and authorization during local development to work in the same manner as it would when the application is deployed to Choreo, eliminating the need to modify the source code. - -Choreo's local development capability ensures a seamless local application development experience where the authentication and authorization process aligns with Choreo’s deployment environment. This facilitates a smoother transition from development to deployment, improving workflow efficiency. - -## How local development works in Choreo - -Local development uses a proxy that sits in front of the locally running web application. This proxy intercepts all incoming requests. The requests to `/choreo-apis/*` and `/auth/*` are then forwarded to Choreo, while all other requests are forwarded to the locally running web application. The proxy runs on HTTPS using a self-signed certificate, crucial for secure, HTTP-only cookie-based managed authentication. Upon running the proxy, you can access the web application using the proxy's URL and start developing the application locally. You will observe that the behavior of the web application, in terms of the managed authentication functionality, is similar to how it would be after deploying to Choreo. - -## Configure local development - -### Prerequisites - -- Create a single-page application (SPA) with managed authentication enabled. For details on how to set up managed authentication for your web application, see [Secure Web Applications with Managed Authentication](../../authentication-and-authorization/secure-web-applications-with-managed-authentication.md#step-1-set-up-managed-authentication-for-your-web-application). -- Promote and deploy the application to the environment where you want to enable local development. - - !!! note - - The web application that you run locally will use the same managed authentication configuration as the environment where you are configuring local development. - - Local development is only allowed in non-critical environments. - - -### Apply configurations - -1. Sign in to the Choreo Console. -2. In the **Component Listing** pane, click on the component you created and deployed by following the prerequisites. -3. In the left navigation menu, click **Deploy**. -4. Go to the respective environment card depending on the environment where you want to enable local development and click **Local Development**. -5. In the **Local Development** pane that opens, click the **Local Development** toggle to enable it. -6. If you want to update the port on which the local development proxy server runs, click to expand **Advanced Configurations** and specify a value for **Proxy Port**. -7. Click **Apply**. - -Now you have done the necessary configurations to set up local development. The next section walks you through the steps to access your web application so that you can develop it locally. - -## Access your web application to develop it locally - -### Prerequisites - -- Ensure that local development is enabled in the environment where you want to proceed with local development. -- Ensure that your web application is running locally on `http://localhost` on a specific port. - -### Access your web application locally - -You can either use the Choreo built-in identity provider or external identity provider to access your web application locally. - -=== "Use the Choreo built-in identity provider" - - 1. Sign in to the Choreo Console. - 2. In the **Component Listing** pane, click on the component you created and deployed by following the prerequisites. - 3. In the left navigation menu, click **Deploy**. - 4. Go to the respective environment card depending on the environment where you want to enable local development and click **Local Development**. - 5. In the **Local Development** pane that opens, copy the command given under **Step 1**. - 6. Paste the command in a terminal, ensure you replace [APP_PORT] with the port on which your application is running locally, and run the command. - 7. To access the application and proceed to develop it, go to the URL given under **Step 2** in the **Local Development** pane. - - !!!note - The local development proxy runs on HTTPS using a self-signed certificate. Your browser may warn that the certificate is not valid. Accept the risk and proceed. - - -=== "Use an external identity provider" - - 1. Sign in to the Choreo Console. - 2. In the **Component Listing** pane, click on the component you created and deployed by following the prerequisites. - 3. In the left navigation menu, click **Deploy**. - 4. Go to the respective environment card depending on the environment where you want to enable local development and click **Local Development**. - 5. In the **Local Development** pane that opens, copy the redirect URLs given under **Step 1**. - 6. Go to the settings in the OAuth application in your identity provider and specify the copied URLs as allowed redirect URLs. - 7. Go to the **Local Development** pane in the Choreo Console and copy the command given under **Step 2**. - 8. Paste the command in a terminal, ensure you replace [APP_PORT] with the port on which your application is running locally, and run the command. - 10. To access the application and proceed to develop it, go to the URL given under **Step 3** in the **Local Development** pane. - - !!!note - The local development proxy runs on HTTPS using a self-signed certificate. Your browser may warn that the certificate is not valid. Accept the risk and proceed. - diff --git a/en/docs/develop-components/sharing-and-reusing/use-a-database-connection-in-your-component.md b/en/docs/develop-components/sharing-and-reusing/use-a-database-connection-in-your-component.md deleted file mode 100644 index b0afb143b..000000000 --- a/en/docs/develop-components/sharing-and-reusing/use-a-database-connection-in-your-component.md +++ /dev/null @@ -1,116 +0,0 @@ -# Use a Database Connection in Your Component - -Choreo allows you to share and reuse Choreo-managed databases, accelerating development and enhancing efficiency in building integrated applications through connections. - -For step-by-step instructions on creating a database connection, see [Create a Connection](create-a-connection.md). - -To learn more about Choreo Connections, see the documentation on [Connections](../../choreo-concepts/connections.md). - -## Consume a database through a connection - -To consume a Choreo-managed database via a connection, follow these steps: - -### Step 1: Add connection configurations - -1. Copy and paste the snippet from the inline developer guide into the `component-config` file under the `spec` section. - - The following is a sample snippet: - - ``` yaml - - outbound: - serviceReferences: - - name: database:hrdbProd - connectionConfig: 01ef700c-e378-138e-a11f-6e8e5a924f54 - env: - - from: HostName - to: - - from: Port - to: - - from: Username - to: - - from: Password - to: - - from: DatabaseName - to: - - ``` - - | Field | Description | - |------------------|-------------------------------------------------------------| - | Name | The name of the database you are connecting to. | - | ConnectionConfig | The unique connection identifier for the connection. | - | env | The environment variable mapping. | - | from | The key of the configuration entry. | - | to | The environment variable name to which Choreo will inject the value of the key.| - - -2. Replace `` with appropriate environment variable names. If you have already added an outbound service reference, append this as another entry under `serviceReferences`. - - The following table provides details on the configuration keys associated with the connection: - - | Name | Type | Description |Optional | Sensitive | - |--------------|---------|----------------------------------------------------------------------|---------------|--------------| - | HostName | string | The hostname of the database server where the database resides. | false | false | - | Port | string | The port number on which the database server listens for connections.| false | false | - | Username | string | The username for database access. | false | false | - | Password | string | The password for database access. | false | true | - | DatabaseName | string | The name of the database to connect. | false | false | - -### Step 2: Read configurations within the application - -Once you add the connection configuration snippet, you can read the configurations within your application. The steps to follow depend on the programming language you are using. - -The following is a sample code snippet in JavaScript: - -``` java -const hostName = process.env.HOST_NAME; -``` - -### Step 3: Initiate a database connection - -To initiate a connection to the database, follow these steps: - -In this example, you will connect to a MySQL database. - -#### Step 3.1: Install the required packages - -For the MySQL database, install the `mysql2` package using npm: - -``` bash -// Install the mysql2 package -npm install mysql2 - -``` - -#### Step 3.2: Import required packages - -``` java - -const client = require('mysql2') - -``` - -#### Step 3.3: Establish a connection - -To establish the connection, use the environment variables for `hostName`, `username`, `password`, `databaseName`, and `port` as follows: - -``` java - -var connection = client.createConnection({ - host: hostName, - user: username, - password: password, - database: databaseName, - port: port -}); - -connection.connect((err) => { - if (err) { - return; - } - // Connection is successful -}); - -``` -By following these steps, your component can interact with the Choreo-managed database seamlessly. diff --git a/en/docs/devops-and-ci-cd/manage-environments.md b/en/docs/devops-and-ci-cd/manage-environments.md deleted file mode 100644 index c1b1cf621..000000000 --- a/en/docs/devops-and-ci-cd/manage-environments.md +++ /dev/null @@ -1,58 +0,0 @@ -# Manage Environments - -By default, all projects created in the cloud data planes (irrespective of the data plane region) are provisioned with two environments (i.e., development and production). - -The environments are listed in the order of deployment and promotion. The initial deployment takes place in the first environment and you can proceed to promote a component to subsequent environments. - -## Create a new environment - -### Prerequisites - -- To create additional environments, you must have a Choreo subscription or a private data plane. -- To create a new environment in a private data plane organization, you must have the `ENVIRONMENT-MANAGEMENT` permission. By default, `ENVIRONMENT-MANAGEMENT` permission is granted to Admin and Choreo DevOps roles. - -To create a new environment, follow the steps given below: - -1. Sign in to the [Choreo Console](https://console.choreo.dev/) and switch to the organization where you want to create a new project. -2. In the left navigation menu, click **DevOps** and then click **Environments** (note that this is the **Environments** page under your organization, not your projects). -3. On the **Environments** page, click **Create** and specify the following details to create a new environment: - - - **Name**: A display name for the new environment. - - **Data Plane** - The data plane to create the new environment. - - !!!tip - The **Data Plane** list displays all the private data planes registered under your organization. - - - **DNS Prefix**: A DNS prefix to identify the exposed APIs in the environment. Here, the base domain depends on the custom domain attached to the API gateways provisioned on the selected data plane. - - **Mark environment as a Production environment**: Select if you want this environment to be a production environment. - - !!!tip - In Choreo, you can have multiple non-production and production environments. To work in a production environment, you must have privileged permissions to access and deploy to production environments. - -## Change the order of promotion - -The order in which environments are listed on the **Environments** page is the same order in which promotion takes place. - -To change the order of promotion across environments in an organization, follow the steps given below: - -1. Sign in to the [Choreo Console](https://console.choreo.dev/) and switch to the organization for which you want to change the order of promotion. -2. In the left navigation menu, click **DevOps** and then click **Environments**. -3. On the **Environments** page, click and drag environment list items to rearrange the order of listed environments. - - !!! note - Although changes to the order of promotion for environments are applied immediately, the change does not affect the components already running in environments. Only subsequent builds and promotions will follow the new order. - -To see the changes, go to the **Deploy** page of a component (in any project). - -## Delete an environment - -To delete an environment, follow the steps given below: - -!!! warning - Environment deletion is a permanent, non-reversible operation. - -1. Sign in to the [Choreo Console](https://console.choreo.dev/) and switch to your organization. -2. In the left navigation menu, click **DevOps** and then click **Environments**. -3. In the **Environments** list, click the delete icon corresponding to the environment you want to delete. This displays a confirmation dialog with details on the impact of deletion. -4. Review the details, then type the environment name to confirm the deletion. -5. Click **Delete**. diff --git a/en/docs/monitoring-and-insights/alerts/configure-alerts.md b/en/docs/monitoring-and-insights/alerts/configure-alerts.md deleted file mode 100644 index 1efb37f16..000000000 --- a/en/docs/monitoring-and-insights/alerts/configure-alerts.md +++ /dev/null @@ -1,82 +0,0 @@ -# Configure Alerts - -This section explains how you can configure alerts for your API manager deployments. Setting up alerts allows you to proactively monitor your API ecosystem and take corrective measures when necessary. - -You can configure alerts for each environment within your organization. You can add, modify, or delete alerts per API. Optionally, you can specify a list of emails for each alert configuration. - -Alerts are subject to a suppression policy to prevent duplicate notifications within a specific time frame. By default, a 10-minute suppression window is applied, and this is not configurable. The suppression policy is specific to each alert configuration. - -!!! info - - You can configure a maximum of 20 alerts per organization, environment, and tenant combination. - - Adding email addresses to an alert configuration is optional. If necessary, you can add a maximum of 5 email addresses per alert. - -Alerts can be categorized as either [latency alerts](#latency-alerts) or [traffic alerts](#traffic-alerts). - -## Latency alerts - -Latency alerts notify you if the response latency of an API exceeds a predefined threshold. This is useful for APIs that need to meet specific SLAs and for proactively identifying slow APIs. - -To configure a new latency alert, follow the steps given below: - -1. Sign in to the [Choreo Console](https://console.choreo.dev/). -2. Ensure you are in the correct organization where you have a project with the API to configure a latency alert. -3. In the Choreo Console left navigation menu, click **Usage Insights**. -4. In the left navigation menu on the **Usage Insights** page, click **Alerts**. -5. Click the **Environment** list and select the required environment. -6. Click **Alert Configuration**. - - ![Configure alerts](../../assets/img/monitoring-and-insights/alerts/alert-configuration.png){.cInlineImage-full} - - This opens the **Alert Configuration** pane with the **Latency** tab open by default. - -7. In the **API Name** field, select the API for which you want to configure the alert. - - !!! Info - Only the APIs that you have invoked at least once are listed here. For other APIs, you need to give the API name in the required format as instructed in the UI. - -8. In the **Metric** field, select the required metric against which you want to evaluate the alert configuration. - - !!! tip - The list includes all available options. If there are multiple metrics, you can select the required metric. If there is only one metric to choose, that metric is selected by default, and the field is disabled. - -9. In the **Latency** field, specify the threshold in milliseconds. - - !!! info - When the 95th percentile of the selected metric exceeds the threshold provided here, alerts are triggered. - -10. In the **Emails** field, specify the list of emails that should be notified when the alert is added. - -11. Click **+ Add**. - -Once an alert is successfully added, the alert configuration is listed in the **Alert Configuration** pane. Each configuration can be edited and removed via this pane. - -## Traffic alerts - -Traffic alerts notify you when the request count of an API exceeds a predefined threshold. This is useful for managing APIs with backend traffic limits or monetized backends that require proactive scaling based on incoming traffic. - -To configure a new traffic alert, follow the steps below: - -1. Sign in to the [Choreo Console](https://console.choreo.dev/). -2. Ensure you are in the correct organization where you have a project with the API to configure a latency alert. -3. In the Choreo Console left navigation menu, click **Usage Insights**. -4. In the left navigation menu on the **Usage Insights** page, click **Alerts**. -5. Click the **Environment** list and select the required environment. -6. Click **Alert Configuration**. This opens the **Alert Configuration** pane. -7. Click the **Traffic** tab. -8. In the **API Name** field, select the API for which you want to configure the alert. - - !!! Info - Only the APIs that you have invoked at least once are listed here. For other APIs, you need to give the API name in the required format as instructed in the UI. - -9. In the **Metric** field, select the required metric against which you want to evaluate the alert configuration. - - !!! tip - The list includes all available options. If there are multiple metrics, you can select the required metric. If there is only one metric to choose, that metric is selected by default, and the field is disabled. - -10. In the **Threshold** field, specify the threshold number of requests per minute. - -11. If required, specify the list of emails that should be notified when the alert is generated in the **Emails** field. - -12. Click **Add**. - -Once an alert is successfully added, the alert configuration is listed in the **Alert Configuration** pane. Each configuration can be edited and removed via this pane. diff --git a/en/docs/quick-start-guides/deploy-a-web-application-that-consumes-a-backend-service.md b/en/docs/quick-start-guides/deploy-a-web-application-that-consumes-a-backend-service.md deleted file mode 100644 index 2a0b246e1..000000000 --- a/en/docs/quick-start-guides/deploy-a-web-application-that-consumes-a-backend-service.md +++ /dev/null @@ -1,322 +0,0 @@ -# Deploy a Web Application that Consumes a Backend Service - -Choreo is an Internal Developer Platform (IDevP) that streamlines the entire process of building, deploying, monitoring, and managing your cloud-native applications easily. - -In this quick start guide, you will explore how to expose a service endpoint via Choreo and securely consume the service from a web application. You will use a simple reading list web application with a sign-in page and functionality to interact with a secure backend service. You will also use Choreo's managed authentication to easily set up authentication for your web application without having to dive into the details of security protocols. The application will allow users to sign in and view their reading lists, add books to a reading list, delete books from the reading list, and sign out of the application effortlessly. - -This guide walks you through the following steps: - -- Deploy and test a service component. -- Create a web application to consume the exposed service. -- Create a connection to the deployed service. -- Enable managed authentication and deploy the web application. -- Consume the deployed service via the web application. - - -## Prerequisites - -Before you try out this guide, complete the following: - -1. Create a GitHub repository to save the service implementation. For this guide, you can fork the [Choreo sample book list app repository](https://github.com/wso2/choreo-sample-book-list-app). - -2. If you are signing in to the Choreo Console for the first time, create an organization as follows: - - 1. Go to [https://console.choreo.dev/](https://console.choreo.dev/), and sign in using your Google, GitHub, or Microsoft account. - 2. Enter a unique organization name. For example, `Stark Industries`. - 3. Read and accept the privacy policy and terms of use. - 4. Click **Create**. - - This creates the organization and opens the organization home page. - -## Step 1: Create a project - -Follow the steps given below to create a project: - -1. Go to [https://console.choreo.dev/](https://console.choreo.dev/) and sign in. This opens the organization home page. -2. On the organization home page, click **+ Create Project**. -3. Enter a display name, unique name, and description for the project. You can enter the values given below: - - !!! tip - In the **Name** field, you must specify a name to uniquely identify your project in various contexts. The value is editable only at the time you create the project. You cannot change the name after you create the project. - - | **Field** | **Value** | - |--------------------------|-----------------------| - | **Project Display Name** | `Sample project` | - | **Name** | `sample-project` | - | **Project Description** | `My sample project` | - -4. Click **Create**. This creates the project and opens the project home page. - -## Step 2: Connect your sample repository and configure the sample service - -To connect to the repository you forked in the prerequisites and configure the sample service, follow the steps given below: - -1. On the project home page, click **Start** under **Create Multiple Components**. -2. Go to the **GitHub** tab. -3. To allow Choreo to connect to your GitHub account, click **Authorize with GitHub**. If you have not already connected your GitHub repository to Choreo, enter your GitHub credentials and select the repository you created in the prerequisites section to install the [Choreo GitHub App](https://github.com/marketplace/choreo-apps). - - Alternatively, you can paste the [Choreo sample book list app repository](https://github.com/wso2/choreo-sample-book-list-app) URL in the **Provide Repository URL** field to connect to it without requiring authorization from the [Choreo Apps](https://github.com/marketplace/choreo-apps) GitHub application. However, authorizing the repository with the [Choreo GitHub App](https://github.com/marketplace/choreo-apps) is necessary if you want to enable [**Auto Deploy**](https://wso2.com/choreo/docs/choreo-concepts/ci-cd/#deploy) for the component. - - !!! note - The **Choreo GitHub App** requires the following permissions: - - - Read and write access to code and pull requests. - - Read access to issues and metadata. - - You can [revoke access](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/reviewing-your-authorized-integrations#reviewing-your-authorized-github-apps) if you do not want Choreo to have access to your GitHub account. However, write access is exclusively utilized for sending pull requests to a user repository. Choreo will not directly push any changes to a repository. - -4. Enter the following information: - - | **Field** | **Value** | - |------------------------------|-----------------------------| - | **Organization** | Your GitHub account | - | **Repository** | choreo-sample-book-list-app | - | **Branch** | **`main`** | - -5. In the **Add Component Directories** pane under **Configure Components**, click the **+** icon corresponding to `reading-list-service`. -6. In the **Component Configuration** dialog that opens, specify values as follows for each of the fields: - - | **Field** | **Value** | - |---------------------------|-----------------------------------------------| - | **Component Display Name**| Reading List Service | - | **Component Name** | reading-list-service | - | **Path** | reading-list-service | - | **Component Type** | Service | - | **Buildpack** | NodeJS | - | **Language Version** | 20.x.x | - -7. Click **Save**. This adds the `Reading List Service` component to the **Configured Components** pane. -8. Click **Finish**. This initializes the service with the implementation from your GitHub repository and takes you to the project home page. - - You can see the `Reading List Service` component listed under **Component Listing** on the project home page. - -## Step 3: Build the service - -To build the service, follow the steps given below: - -1. On the project home page, click the `Reading List Service` component listed under **Component Listing**. This takes you to the component overview page. -2. In the left navigation menu, click **Build**. -3. In the **Builds** pane, click **Build Latest**. - - !!! note - Building the service component may take a while. You can track the progress via the logs in the **Build Details** pane. Once the build process is complete, the build status changes to **Success**. - -## Step 4: Deploy the service - -For the REST endpoint of the service to be invokable, you need to deploy it. To deploy the service, follow the steps given below: - -1. In the left navigation menu, click **Deploy**. -2. In the **Set Up** card, click **Configure & Deploy**. -3. In the **Environment Configurations** pane that opens, click **Next** to skip the configuration. -4. In the **File Mount** pane that opens, click **Next** to skip the configuration. -5. In the **Endpoint Details** pane that opens, verify that the **Network Visibility** is set to **Public**. This setting securely exposes the endpoint for consumption. -6. Click **Deploy**. This deploys the service to the development environment and lists the service in the [Choreo Marketplace](../choreo-concepts/choreo-marketplace.md). - -## Step 5: Test the service - -To test the endpoint via the integrated OpenAPI Console in Choreo, follow the steps given below: - -1. In the Choreo Console left navigation menu, click **Test** and then click **Console**. -2. In the OpenAPI Console that opens, select **Development** from the environment drop-down list. -3. In the **Endpoint** list, select **Books REST Endpoint**. -4. Expand the **GET/books** method, click **Try it out**, then click **Execute**. -5. Click . -6. Check the **Server Response** section. You will see an empty response. You can add an entry using the POST method and retry the **GET/books** method again. -7. Expand the **POST/books** method and click **Try it out**. -8. Update the request body so that the parameters have the values given below: - - | **Parameter** | **Value** | - |---------------|---------------| - | **author** | Bram Stoker | - | **status** | to_read | - | **title** | Dracula | - - The request body should look as follows: - - ```json - { - "author": "Bram Stoker", - "status": "to_read", - "title": "Dracula" - } - ``` -9. Click **Execute**. - - Check the **Server Response** section. On successful invocation, you will receive the `201` HTTP code. - -Similarly, you can expand and try out the **GET** and **DELETE** methods. - -## Step 6: Consume the service - -Now that the `Reading List Service` is deployed and available in the Choreo Marketplace, application developers can discover the service via the Marketplace and consume it. - -In this section of the guide, you will deploy a sample front-end application to consume the service. This application will serve as the interface for users to interact with the reading list. The sample application used in this guide is designed to personalize the book lists based on the user ID that it obtains from its identity provider. - -To host the front-end application in Choreo, you will create a web application component, set up authentication for it, and deploy it. To establish a connection between your web application and the deployed service, you will create a Connection. - -### Step 6.1: Create a web application to consume the service - -To create a web application component, follow the steps given below: - -1. In the Choreo Console header, click the **Project** list and select the project that you created in step 1. -2. On the project home page, click **+ Create** under **Component Listing**. -3. Click the **Web Application** card. -4. Enter a display name, unique name, and a description to create the web application. You can enter the values given below: - - !!! info - In the **Component Name** field, you must specify a name to uniquely identify the component in various contexts. The value is editable only at the time you create the component. You cannot change the name after you create the component. - - |Field | Value | - |----------------------|------------------------| - |Component Display Name| Reading List Web App | - |Component Name | reading-list-web-app | - |Description | Front-end application for the reading list service | - -5. Go to the **GitHub** tab. -6. To allow Choreo to connect to your GitHub account, click **Authorize with GitHub**. If you have not already connected your GitHub repository to Choreo, enter your GitHub credentials and select the repository you created in the prerequisites section to install the [Choreo GitHub App](https://github.com/marketplace/choreo-apps). - - Alternatively, you can paste the [Choreo sample Book List Service repository](https://github.com/wso2/choreo-sample-book-list-service) URL in the **Provide Repository URL** field to connect to it without requiring authorization from the [Choreo Apps](https://github.com/marketplace/choreo-apps) GitHub application. However, authorizing the repository with the [Choreo GitHub App](https://github.com/marketplace/choreo-apps) is necessary if you want to enable [**Auto Deploy**](https://wso2.com/choreo/docs/choreo-concepts/ci-cd/#deploy) for the component. - - !!! note - The **Choreo GitHub App** requires the following permissions: - - - Read and write access to code and pull requests. - - Read access to issues and metadata. - - You can [revoke access](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/reviewing-your-authorized-integrations#reviewing-your-authorized-github-apps) if you do not want Choreo to have access to your GitHub account. However, write access is exclusively utilized for sending pull requests to a user repository. Choreo will not directly push any changes to a repository. - -7. Enter the following information: - - | **Field** | **Description** | - |-----------------------|----------------------------------| - | **Organization** | Your GitHub account | - | **Repository** | choreo-sample-book-list-app | - | **Branch** | main | - -8. Select **React** as the buildpack because the sample front-end application is a React application built with Vite. -9. Enter the following information: - - | **Field** | **Value** | - |-----------------------|-------------------------| - | **Project Directory** | /choreo-sample-book-list-app/reading-list-front-end-with-managed-auth | - | **Build Command** | npm install && npm run build | - | **Build Path** | dist | - | **Node Version** | 18 | - -10. Click **Create**. This initializes the component with the implementation from your GitHub repository and takes you to the **Overview** page of the component. - -### Step 6.2: Create a connection between the web application and the deployed service - -A connection allows you to integrate the service you intend to deploy on Choreo with other services on Choreo or external resources. For more information on Choreo Connections refer to the [Connection](../choreo-concepts/connections.md) documentation. - -To establish a connection between the web application you created and the deployed service, follow the steps given below: - -1. In the left navigation menu, click **Dependencies** and then click **Connections**. -2. Click **+ Create**. -3. In the **Select a Service** pane, click `Reading List Service`.` -4. Specify values as follows for each of the fields: - - | **Field** | **Value** | - |------------------|-------------------------------| - | **Name** | Reading List Connection | - | **Description** | Connection to the reading list| - -5. Click **Create**. This creates the connection and displays the service URL of the connection for -each environment the service is deployed in. In this guide, you will see the service URL for the Development environment. You can copy the service URL to use when you configure the web application before deploying it. - -### Step 6.3: Build the web application component - -To build the web application, follow the steps given below: - -1. In the left navigation menu, click **Build**. -2. In the **Builds** pane, click **Build Latest**. - - !!! note - Building the service component may take a while. You can track the progress via the logs in the **Build Details** pane. Once the build process is complete, the build status changes to **Success**. - -### Step 6.4: Configure and deploy the web application - -In this step, you will configure managed authentication, create a user to access the web application, and then deploy the web application. For more information on Choreo's managed authentication capability, see the [Managed Authentication](../authentication-and-authorization/secure-web-applications-with-managed-authentication.md) documentation. - -To configure managed authentication, follow the steps given below: - -1. In the left navigation menu, click **Deploy**. -2. In the **Set Up** card, click **Configure and Deploy**. This opens the **Configure & Deploy** pane, where you can specify values for the mount file. -3. Specify the following in the `config.js` file mount. - - You must replace `` with the value that you copied when creating a connection to the `Reading List Service` in [step 6.2](#step-62-create-a-connection-between-the-web-application-and-the-deployed-service). - - ```javascript - window.configs = { - apiUrl: '', - }; - ``` - - !!! tip - You can refer to the configuration file mounted at `/app/public` as `./public/config.js` within your web application. - -4. Click **Next**. This opens the **Authentication** pane. -5. Under **Authentication Settings**, make sure that you have the **Managed authentication with Choreo** toggle enabled. - - !!! tip - Managed authentication is enabled by default when you create a web application using **React**, **Angular**, or **Vue.js** buildpacks. - -6. Specify values as follows for each of the fields: - - | **Field** | **Value** | - |---------------------|------------| - | **Post Login Path** | / | - | **Post Logout Path**| / | - | **Error Path** | / | - -Next, you can create a user to access the web application. - -To create a user to access the **readingListApp** application, follow the steps given below: - -1. Under **Manage Users**, click **+ Create**. -2. To proceed with creating a user with the populated username and password, click **Create**. Make sure you copy the populated username and password to use when you test the front-end application. - - !!! tip - - By default, your test user base consists of a demo user. For instructions on how to modify the test user base, see [Configure a User Store with the Built-In Identity Provider](../administer/configure-a-user-store-with-built-in-idp.md). - -Now, you can deploy the web application. - -To deploy the web application and obtain the URL to access it, follow the steps given below: - -1. In the **Authentication** pane, click **Deploy**. The deployment may take a few minutes to complete. -2. Once you deploy the web application, copy the **Web App URL** from the development environment card. -3. Navigate to the web app URL. You can verify that you have successfully hosted the web application. - -## Step 7: Test the front-end application - -To test the front-end application and send requests to the **Reading List Service** via it, follow the steps given below: - -1. Access the front-end application via its web URL that you copied in the above step. -2. Click **Login**, and sign in with the credentials of the user that you created. - - The application opens as follows. - - ![Front-end application](../assets/img/quick-start-guides/front-end-application.png){.cInlineImage-half} - -3. Add three new reading items with different statuses. - - For example, the details can be as follows: - - | **Title** | **Author** | **Status** | - |---------------------------|-------------------|------------| - | The Museum of Innocence | Orhan Pamuk | reading | - | The Remains of the Day | Kazuo Ishiguro | to_read | - | David Copperfield | Charles Dickens | read | - - To add each record, follow the steps given below: - - 1. Click **+ Add New**. - 2. Enter values for the **Name**, **Author**, and **Status** fields. - 3. Click **Save**. - - Three tabs open for each status. To delete a reading list item, you can click **Delete**. - -To verify whether the reading list is personalized for each user, you can sign in as a different user. The reading list items you entered above will not appear for the other user. - -Congratulations! You have successfully exposed a service endpoint via Choreo and securely consumed it from a web application. - -After you have successfully tested your service and web application, you can now try out various other Choreo features such as [managing](../api-management/lifecycle-management.md), [observing](../monitoring-and-insights/observability-overview.md), [DevOps](../devops-and-ci-cd/view-runtime-details.md), etc., similar to any other component type within Choreo. diff --git a/en/docs/quick-start-guides/deploy-your-first-service.md b/en/docs/quick-start-guides/deploy-your-first-service.md deleted file mode 100644 index 48c3f1846..000000000 --- a/en/docs/quick-start-guides/deploy-your-first-service.md +++ /dev/null @@ -1,148 +0,0 @@ -# Deploy Your First Service - -Choreo, an Internal Developer Platform (IDevP), simplifies the deployment, monitoring, and management of your cloud-native services, allowing you to focus on innovation and implementation. - -Choreo allows you to easily deploy services you've created in your preferred programming language in just a few steps. - -In this guide, you will: - -- Use a pre-implemented service that has resources to maintain a book list. -- Build and deploy the service in Choreo using the `Nodejs` buildpack. It runs on port 8080. -- Test the service. - -For a video tutorial that walks you through these steps, see [Deploy Your First Service with Choreo](https://www.youtube.com/watch?v=-qoweQWCiYM). - -## Prerequisites - -1. You must have a GitHub account with a repository that contains your service implementation. To proceed with the steps in this guide, you can fork the [Choreo sample book list service repository](https://github.com/wso2/choreo-sample-book-list-service/), which contains the sample for this guide. - -2. If you are signing in to the Choreo Console for the first time, create an organization as follows: - - 1. Go to [https://console.choreo.dev/](https://console.choreo.dev/), and sign in using your Google, GitHub, or Microsoft account. - 2. Enter a unique organization name. For example, `Stark Industries`. - 3. Read and accept the privacy policy and terms of use. - 4. Click **Create**. - - This creates the organization and opens the organization home page. - -### Learn the repository file structure - -Let's familiarize ourselves with the key files in this sample application. The below table gives a brief overview of the important files in the sample book list service. - -!!! note - The following file paths are relative to the path `/`. - -|Filepath |Description | -|-----------------------|------------------------------------------------------------------------------| -|app.mjs |The Node.js (JavaScript) based service code.| -|.choreo/component.yaml |Choreo-specific configuration that provides information about how Choreo exposes the service.| -|openapi.yaml |OpenAPI contract of the service. This is required to publish our service as a managed API. This openapi.yaml file is referenced by the .choreo/component.yaml.| - -Let's get started! - -## Step 1: Create a project - -Follow the steps given below to create a project: - -1. Go to [https://console.choreo.dev/](https://console.choreo.dev/) and sign in. This opens the organization home page. -2. On the organization home page, click **+ Create Project**. -3. Enter a display name, unique name, and description for the project. You can enter the values given below: - - !!! info - In the **Name** field, you must specify a name to uniquely identify your project in various contexts. The value is editable only at the time you create the project. You cannot change the name after you create the project. - - | **Field** | **Value** | - |--------------------------|------------------------------------| - | **Project Display Name** | Book List Project | - | **Name** | book-list-project | - | **Project Description** | My sample project | - -4. Click **Create**. This creates the project and takes you to the project home page. - -## Step 2: Create a service component - -Let's create a service component by following these steps: - -1. On the project home page, click **Service** under **Create a Component**. -2. Enter a unique name and a description for the service. For this guide, let's enter the following values: - - |Field | Value | - |----------------------|------------------------| - |Component Display Name| Book List | - |Description | Gets the book list | - -3. Go to the **GitHub** tab. -4. To allow Choreo to connect to your GitHub account, click **Authorize with GitHub**. If you have not already connected your GitHub repository to Choreo, enter your GitHub credentials and select the repository you created in the prerequisites section to install the [Choreo GitHub App](https://github.com/marketplace/choreo-apps). - - Alternatively, you can paste the [Choreo sample Book List Service repository](https://github.com/wso2/choreo-sample-book-list-service) URL in the **Provide Repository URL** field to connect to it without requiring authorization from the [Choreo Apps](https://github.com/marketplace/choreo-apps) GitHub application. However, authorizing the repository with the [Choreo GitHub App](https://github.com/marketplace/choreo-apps) is necessary if you want to enable [**Auto Deploy**](https://wso2.com/choreo/docs/choreo-concepts/ci-cd/#deploy) for the component. - - !!! note - The **Choreo GitHub App** requires the following permissions: - - - Read and write access to code and pull requests. - - Read access to issues and metadata. - - You can [revoke access](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/reviewing-your-authorized-integrations#reviewing-your-authorized-github-apps) if you do not want Choreo to have access to your GitHub account. However, write access is exclusively utilized for sending pull requests to a user repository. Choreo will not directly push any changes to a repository. - -5. Enter the following information: - - | **Field** | **Description** | - |-----------------------|----------------------------------| - | **Organization** | Your GitHub account | - | **Repository** | choreo-sample-book-list-service | - | **Branch** | main | - -6. Select the **NodeJS** buildpack. -7. Enter the following information. - - | **Field** | **Description** | - |------------------------------|-------------------| - | **NodeJS Project Directory** | / | - | **Language Version** | 20.x.x | - -8. Click **Create**. - -You have successfully created a Service component with the NodeJS buildpack. Now let's build and deploy the service. - -## Step 3: Build and deploy - -Now that the source repository is connected and Choreo has set up the endpoints based on the repository's configuration, it's time to proceed with building the service. Choreo will create a Docker image in the build process. You can then deploy the built Docker image and test the book list service. - -### Step 3.1: Build - -To build the service, follow these steps: - -1. On the project home page, click the `Book List` component listed under **Component Listing**. This takes you to the component overview page. -2. In the left navigation, click **Build**. -3. Click **Build Latest**. - - !!! note - Building the service component may take a while. You can track the progress via the logs in the **Build Details** pane. Once the build process is complete, the build status changes to **Success**. - -### Step 3.2: Deploy - -Now you are ready to deploy the service. Follow these steps: - -1. In the left navigation menu, click **Deploy**. -2. On the **Set Up** card, click **Configure & Deploy**. -3. In the **Environment Configurations** pane, click **Next**. -4. In the **File Mount** pane, click **Next**. -5. Review the **Endpoint Details** and click **Deploy**. - - !!! note - Deploying the service component may take a while. You can track the progress by observing the logs. Once the deployment is complete, the build status changes to **Active** on the **Development** environment card. - -## Step 4: Test the service - -To test the **Book List** service via the integrated OpenAPI Console in Choreo, follow the steps given below: - -1. In the Choreo Console left navigation menu, click **Test** and then click **Console**. -2. In the OpenAPI Console that opens, select **Development** from the environment drop-down list. -3. In the **Endpoint** list, select **Books REST Endpoint**. -4. Expand the **GET /books** method and click **Try it out**. -5. Click **Execute**. -6. Check the **Server Response** section. - -Similarly, you can expand and try out the other methods. - -After you have successfully tested your service, you can now try out various other Choreo features such as [managing](../api-management/lifecycle-management.md), [observing](../monitoring-and-insights/observability-overview.md), [DevOps](../devops-and-ci-cd/view-runtime-details.md), etc., similar to any other component type within Choreo. diff --git a/en/docs/quick-start-guides/deploy-your-first-static-web-application.md b/en/docs/quick-start-guides/deploy-your-first-static-web-application.md deleted file mode 100644 index 7beabb0e2..000000000 --- a/en/docs/quick-start-guides/deploy-your-first-static-web-application.md +++ /dev/null @@ -1,109 +0,0 @@ -# Deploy Your First Static Web Application - -Choreo is an internal developer platform as a service that takes care of the complexities of building platforms, allowing application developers to focus on innovation and implementation. Choreo streamlines the entire process of building, deploying, monitoring, and managing your cloud-native applications. - -In this quick start guide, you will explore how easy it is to deploy a web application using Choreo. Here, you will use a simple web application designed to add tasks to a to-do list. - -This guide walks you through the following steps: - - - Create a project. - - Create a Web Application component and connect it to the GitHub repository that includes the web application implementation. - - Build the web application. - - Deploy the web application and access it. - -For a video tutorial that walks you through these steps, see [Deploy a Static Web App on Choreo](https://www.youtube.com/watch?v=YPBSuLG5l5g). - -## Prerequisites - -Before you try out this guide, complete the following: - -1. Fork the [choreo-sample-todo-list-app - repository](https://github.com/wso2/choreo-sample-todo-list-app), which contains the sample for this guide. -2. If you are signing in to the Choreo Console for the first time, create an organization as follows: - - 1. Go to [https://console.choreo.dev/](https://console.choreo.dev/), and sign in using your Google, GitHub, or Microsoft account. - 2. Enter a unique organization name. For example, `Stark Industries`. - 3. Read and accept the privacy policy and terms of use. - 4. Click **Create**. - - This creates the organization and opens the organization home page. - -## Step 1: Create a project - -Follow the steps given below to create a project: - -1. Go to [https://console.choreo.dev/](https://console.choreo.dev/) and sign in. This opens the organization home page. -2. On the organization home page, click **+ Create Project**. -3. Enter a display name, unique name, and description for the project. You can enter the values given below: - - !!! tip - In the **Name** field, you must specify a name to uniquely identify your project in various contexts. The value is editable only at the time you create the project. You cannot change the name after you create the project. - - | **Field** | **Value** | - |--------------------------|-----------------------| - | **Project Display Name** | `Sample project` | - | **Name** | `sample-project` | - | **Project Description** | `My sample project` | - -4. Click **Create**. This creates the project and opens the project home page. - -## Step 2: Create a Web Application component - -To create a Web Application component, follow the steps given below: - -1. On the project home page, click **Web Application** under **Create a Component**. -2. Enter a unique name and a description for the web application. -3. Go to the **GitHub** tab. -4. To allow Choreo to connect to your GitHub account, click **Authorize with GitHub**. If you have not already connected your GitHub repository to Choreo, enter your GitHub credentials and select the repository you created in the prerequisites section to install the [Choreo GitHub App](https://github.com/marketplace/choreo-apps). - - Alternatively, you can paste the [choreo-sample-todo-list-app repository](https://github.com/wso2/choreo-sample-todo-list-app) URL in the **Provide Repository URL** field to connect to it without requiring authorization from the [Choreo Apps](https://github.com/marketplace/choreo-apps) GitHub application. However, authorizing the repository with the [Choreo GitHub App](https://github.com/marketplace/choreo-apps) is necessary if you want to enable [**Auto Deploy**](https://wso2.com/choreo/docs/choreo-concepts/ci-cd/#deploy) for the component. - - !!! note - The **Choreo GitHub App** requires the following permissions: - - - Read and write access to code and pull requests. - - Read access to issues and metadata. - - You can [revoke access](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/reviewing-your-authorized-integrations#reviewing-your-authorized-github-apps) if you do not want Choreo to have access to your GitHub account. However, write access is exclusively utilized for sending pull requests to a user repository. Choreo will not directly push any changes to a repository. - -5. Enter the following information: - - | **Field** | **Value** | - |------------------------------|-----------------------------| - | **Organization** | Your GitHub account | - | **Repository** | choreo-sample-todo-list-app | - | **Branch** | **`main`** | - -6. Select **NodeJS** as the **Buildpack** -7. Enter the following information: - - | **Field** | **Value** | - |------------------------------|-----------------------------| - | **NodeJS Project Directory** | / | - | **Language Version** | **20.x.x** | - | **Port** | `8080` | - -8. Click **Create**. Choreo initializes the component with the sample implementation and opens the **Overview** page of the component. - -Now let's build and deploy the web application. - -## Step 3: Build your web application - -To build the web application, follow the steps given below: - -1. In the left navigation menu, click **Build**. -2. In the **Builds** pane, click **Build Latest**. - - !!! note - Building the component may take a while. You can track the progress via the logs in the **Build Details** pane. Once the build process is complete, the build status changes to **Success**. - -Now you can proceed to deploy your web application. - -## Step 4: Deploy and access your web application - -1. In the left navigation menu, click **Deploy**. -2. In the **Set Up** card, click **Configure and Deploy**. This opens the **Configure & Deploy** pane, where you can add a file mount if necessary. In this guide you will not add a file mount. -3. Click **Deploy**. The deployment to the Development environment may take a few minutes to complete. On successful deployment, you will see the **Deployment Status** as **Active** in the **Development** card. -4. To verify that you have successfully hosted the web application, click the **Web App URL** on the **Development** card. This takes you to the web application. You can try creating one or more new tasks by specifying an appropriate task ID and task label. - -After you have successfully tested your web application, you can now try out various other Choreo features such as [observability](../monitoring-and-insights/observability-overview.md), [DevOps](../devops-and-ci-cd/view-runtime-details.md), etc., similar to any other component type within Choreo. diff --git a/en/docs/testing/test-rest-endpoints-via-the-openapi-console.md b/en/docs/testing/test-rest-endpoints-via-the-openapi-console.md deleted file mode 100644 index 4a45daeeb..000000000 --- a/en/docs/testing/test-rest-endpoints-via-the-openapi-console.md +++ /dev/null @@ -1,38 +0,0 @@ -# Test REST Endpoints via the OpenAPI Console - -Choreo provides an integrated OpenAPI Console to test REST endpoints of Service components that you create and deploy. -As Choreo uses OAuth2.0 authentication to secure REST APIs, the OpenAPI Console generates test keys to test APIs. - -Follow the steps below to test a REST endpoint via the integrated OpenAPI Console: - -1. Sign in to the [Choreo Console](https://console.choreo.dev/). - -2. In the **Component Listing** pane, click on the component you want to test. - -3. Click **Test** in the left navigation menu and then click **Console**. This opens the **OpenAPI Console** pane. - -4. In the **OpenAPI Console** pane, select the environment from the drop-down list. - -5. Select the required endpoint from the **Endpoint** list. - - !!! note - - The **Network Visibilities** of an endpoint is set in the **component.yaml**. You can set it to **Public**, **Organization**, or **Project**. - - If you have set the **Network Visibilities** of the endpoint in the **component.yaml** to **Public**, go to step 7. - - If you have set the **Network Visibilities** of the endpoint in the **component.yaml** to **Organization**, the endpoint will not be publicly accessible. However, for testing purposes, Choreo offers the ability to create a temporary test URL that is publicly accessible (secured with OAuth 2.0) and remains active for 15 minutes. To generate the temporary URL, proceed with step 6. - -6. If the **Network Visibilities** of the endpoint contains **Organization**, click on **Generate URL** to generate a temporary test URL that will be active for 15 minutes. Else, skip this step. - - !!! note - The temporary test URL will be available **only for 15 minutes** and it will get expired after. You can deactivate the test URL by clicking on the **Deactivate URL** button. - - ![OpenAPI Console](../assets/img/testing/openapi-console-org.png){.cInlineImage-full} - -7. Expand the resource you want to test. - -8. Click **Try it out**. - -9. Enter values for parameters if applicable. - -10. Click **Execute**. You can see the response body under **Responses**. - - ![OpenAPI Console](../assets/img/testing/openapi-console.png){.cInlineImage-full} diff --git a/en/docs/testing/test-websocket-endpoints-via-the-websocket-console.md b/en/docs/testing/test-websocket-endpoints-via-the-websocket-console.md deleted file mode 100644 index 3b4912ca8..000000000 --- a/en/docs/testing/test-websocket-endpoints-via-the-websocket-console.md +++ /dev/null @@ -1,36 +0,0 @@ -# Test WebSocket Endpoints via the WebSocket Console - -Choreo provides an integrated WebSocket Console to test publicly exposed WebSocket endpoints of Service components you create and deploy. The WebSocket Console allows you to connect to your service and exchange messages interactively. Choreo secures WebSocket APIs with OAuth2.0 by default, and the console automatically generates test keys for authenticated API testing. - -Follow the steps below to test a WebSocket endpoint via the WebSocket Console: - -1. Sign in to the [Choreo Console](https://console.choreo.dev/). - -2. In the **Component Listing** pane, click on the component you want to test. - -3. Click **Test** in the left navigation menu and then click **Console**. This opens the **WebSocket Console** pane. - -4. In the **WebSocket Console** pane, select the environment from the drop-down list. - -5. Select the required endpoint from the **Endpoint** list. - - !!! note - - The **Network Visibility** of an endpoint is set in the **endpoints.yaml** file. You can set it to **Public**, **Organization**, or **Project**. - - If you have set the **Network Visibility** of the endpoint to **Public**, proceed to step 7. - - If you have set the **Network Visibility** of the endpoint to **Organization**, it won't be accessible from outside the organization. For testing, Choreo allows you to generate a temporary URL that remains active for 15 minutes. Follow step 6 to generate the URL. - -6. If the **Network Visibility** of the endpoint is set to **Organization**, click **Generate URL** to generate a temporary test URL valid for 15 minutes. Otherwise, skip this step. - - !!! note - The temporary test URL is valid for 15 minutes and will expire after that. If you want to manually deactivate it, click **Deactivate URL**. - - ![WebSocket Console](../assets/img/testing/websocket-console.png){.cInlineImage-full} - -7. Expand the channel you want to test. - -8. Click **Connect** to establish a connection. The connection status will be displayed in the output logs. - -9. Send and receive messages to and from the deployed service. - - !!! note - The maximum connection duration is 15 minutes. After that, the connection terminates. To reconnect, click **Connect** again. diff --git a/en/docs/tutorials/expose-a-service-as-a-managed-api.md b/en/docs/tutorials/expose-a-service-as-a-managed-api.md deleted file mode 100644 index a18191990..000000000 --- a/en/docs/tutorials/expose-a-service-as-a-managed-api.md +++ /dev/null @@ -1,133 +0,0 @@ -# Expose a Service as a Managed API - -Choreo simplifies securely exposing existing services as managed APIs. It also allows you to effectively manage all aspects of an API's lifecycle, security, throttling, and governance so that you can focus more on service development. - -In this tutorial, you will use Choreo to expose a service as an API proxy and publish it to the Choreo Developer Portal for application developers to consume. - -## Prerequisites - -Before you try out this tutorial, complete the following: - -- If you are signing in to the Choreo Console for the first time, create an organization as follows: - - 1. Go to [https://console.choreo.dev/](https://console.choreo.dev/), and sign in using your preferred method. - 2. Enter a unique organization name. For example, `Stark Industries`. - 3. Read and accept the privacy policy and terms of use. - 4. Click **Create**. - - This creates the organization and opens the **Project Home** page of the default project created for you. - - -## Step 1: Create an API proxy - -To create an API proxy, you can either upload an OpenAPI specification or provide an OpenAPI specification URL. In this tutorial, you will use a URL of a sample OpenAPI specification. - -Follow the steps given below: - -1. Go to [https://console.choreo.dev/](https://console.choreo.dev/) and sign in. This opens the project home page. -2. If you already have one or more components in your project, click **+ Create** under **Component Listing**. Otherwise, proceed to the next step. -3. Click the **API Proxy** card. -4. In the **Create an API Proxy** pane that opens, click **Try with sample URL**. -5. Click **Next**. -6. Update the populated API proxy details with the values given in the following table: - - !!! info - In the **Name** field, you must specify a name to uniquely identify the component in various contexts. The value is editable only at the time you create the component. You cannot change the name after you create the component. - - | **Field** | **Value** | - |------------------|---------------------------------------------| - | **Display Name** | `Swagger Petstore` | - | **Name** | `swagger-petstore` | - | **Context** | `api/v3` | - | **Version** | `1.0` | - | **Target** | `https://petstore3.swagger.io/api/v3` | - | **Access Mode** | `External: API is publicly accessible` | - -7. Click **Create**. This creates the component and takes you to the **Overview** page of the component. - -To see the resources of the API proxy, go to the left navigation menu, click **Develop**, and then click **Resources**. - -## Step 2: Deploy the API proxy - -To deploy the API proxy to the development environment, follow the steps given below: - -1. In the left navigation menu, click **Deploy**. -2. In the **Build Area** card, click **Configure & Deploy**. This opens the **Configure & Deploy** pane, where you can select the API access mode depending on how you want the API to be accessible. - - Here, you can select **External** to make the API publicly accessible, and then click **Deploy**. - - Once the deployment is complete, the **Development** card indicates the **Deployment Status** as **Active**. - -Now you are ready to test the API proxy. - -## Step 3: Test the API proxy - -You can test the API proxy in the development environment before promoting it to production. Choreo provides the following options to test your API proxy: -- OpenAPI Console -- cURL - -In this guide, you will use the OpenAPI Console. - -To test the API proxy via the OpenAPI Console, follow the steps given below: - -1. In the left navigation menu, click **Test** and then click **OpenAPI Console**. - - !!! tip - Since the API proxy is secured when it is deployed, you will need a key to invoke it. Choreo automatically generates a key when you navigate to the **OpenAPI Console** pane. - -2. In the **OpenAPI Console** pane, select **Development** from the environment drop-down list. -3. Expand the `GET /pet/findByStatus` method and click **Try it Out** to test it. -4. Select **available** as the status and click **Execute**. You will see a response similar to the following: - - ![API proxy response](../assets/img/tutorials/api-proxy-response.png) - - This indicates that your API proxy is working as expected. - -## Step 4: Promote the API proxy to production - -Once you verify that the API proxy is working as expected in the development environment, you can follow the steps given below to promote it to production: - -1. In the left navigation menu, click **Deploy**. -2. In the **Development** card, click **Promote**. -3. In the **Configure & Deploy** pane that opens, click **Next**. - - !!! tip - If you want to specify a different endpoint for your production environment, you can make the change in the **Configure & Deploy** pane. - - The **Production** card indicates the **Deployment Status** as **Active** when the API proxy is successfully deployed to production. - - If you want to verify that the API proxy is working as expected in production, you can test the API in the production environment. - - Now that your API is deployed in both development and production environments and can be invoked, the next step is to publish it so that consumers can discover and subscribe to it. - -## Step 5: Publish the API proxy - -To publish the API to the Choreo Developer Portal, follow the steps given below: - -1. In the left navigation menu, click **Manage** and then click **Lifecycle**. This opens the **Lifecycle** page, where you can see the different lifecycle stages that an API can be in. You can see that the current lifecycle stage is **Created**. -2. Click **Publish**. -3. In the **Publish API** dialog that opens, click **Confirm** to proceed publishing the API with the specified display name. If you want to change the display name, make the necessary changes and then click **Confirm**. This changes the API lifecycle state to **Published**. - -You can observe that the API lifecycle stage has changed to **Published**. Now the API is available for consumption. API consumers can consume the API via the Choreo Developer Portal. - - -## Step 6: Invoke the API - -To generate credentials for the published API and to invoke it via the Developer Portal, follow the steps below: - -1. In the **Lifecycle Management** pane, click **Go to DevPortal**. This takes you to the Petstore API published to the Choreo Developer Portal. - -2. To generate credentials for testing the API, follow the steps given below: - - 1. In the Developer Portal left navigation menu, click **Production** under **Credentials**. - 2. Click **Generate Credentials**. Choreo generates new tokens and populates the **Consumer Key** and **Consumer Secret** fields. - -3. To invoke the API, follow the steps given below: - - 1. In the Developer Portal left navigation menu, click **Try Out**. - 2. In the **Endpoint** list, select **Development** as the environment to try out the API. - 3. Click **Get Test Key**. This generates an access token. - 4. Expand the `GET /pet/findByStatus` operation and click **Try it out**. - 5. Select **available** as the status and click **Execute**. - -Now you have successfully created, deployed, tested, and published an API proxy using Choreo. diff --git a/en/docs/tutorials/secure-an-api-with-role-based-access-control.md b/en/docs/tutorials/secure-an-api-with-role-based-access-control.md deleted file mode 100644 index c438f7906..000000000 --- a/en/docs/tutorials/secure-an-api-with-role-based-access-control.md +++ /dev/null @@ -1,249 +0,0 @@ -# Secure an API with Role-Based Access Control - -Role-based access control is a flexible and scalable approach to manage access to API resources. In this approach, each user or group is assigned a specific role that determines the permission granted to perform operations on an API resource. - -This tutorial explains how to implement role-based access control using Choreo and Asgardeo. It includes a real-world scenario with instructions to create and publish an API proxy component in Choreo and apply role-based access control. - -## Scenario - -An organization needs to implement a user management service to keep track of users. The service needs to perform the following four operations: - - - List existing users - - List a user - - Create new users - - Delete a user - -There are two types of users in the organization: - - - Human Resource Manager (HR manager) - - Human Resource Officer (HR officer) - -Each user type requires different levels of access to the user management service. - - - The HR manager must have permission to perform the following operations: list existing users, list a user, create new users, and delete a user. - - The HR officer must have permission to perform the following operations: list existing users and list a user. - -## Implement role-based access control with Choreo and Asgardeo - -Let’s take a look at the steps to follow to implement the scenario described above using Choreo and Asgardeo. - -### Prerequisites - -Before you try out this guide, complete the following: - -If you are signing in to the Choreo Console for the first time, create an organization as follows: - - 1. Go to [https://console.choreo.dev/](https://console.choreo.dev/), and sign in using your preferred method. - 2. Enter a unique organization name. For example, `Stark Industries`. - 3. Read and accept the privacy policy and terms of use. - 4. Click **Create**. - -This creates the organization and opens the home page of the default project created for you. - -!!! info "Enable Asgardeo as the key manager" - - If you created your organization in Choreo before the 21st of February 2023, and you have not already enabled Asgardeo as the key manager, follow these steps to enable Asgardeo as the default key manager: - - 1. In the Choreo Console, go to the top navigation menu and click **Organization**. This takes you to the organization's home page. - 2. In the left navigation menu, click **Settings**. - 3. In the header, click the **Organization** list. This will open the organization level settings page. - 4. Click the **API Management** tab and then click **Enable Asgardeo Key Manager**. - 5. In the confirmation dialog that opens, click **Yes**. - - !!!tip - - Enabling Asgardeo as the default key manager has the following effects: - - - Once the Asgardeo Key Manager is enabled, it will act as the default key manager. You cannot disable, change, or remove it. - - Existing applications created via the Developer Portal in your organization will continue to function as usual. However, any new application you create within the organization will use Asgardeo as the key manager. - - New grant types such as **Password**, **Authorization Code**, **PKCE**, and **Implicit**, which were not available in Choreo will become available. - - The capability to add an external IdP will be disabled because Asgardeo does not support token exchange. However, you can use the [federation capabilities of Asgardeo](https://wso2.com/asgardeo/docs/get-started/asgardeo-use-cases/#identity-federation) to achieve similar functionality. - - -### Step 1: Create an API proxy component and deploy it - -Follow these steps to create an API proxy component, add resources, and deploy it: - -1. Go to [https://console.choreo.dev/](https://console.choreo.dev/cloud-native-app-developer) and sign in. This opens the project home page. -2. To create an API proxy component, follow the instructions in [Develop an API Proxy: Step 1](../develop-components/develop-an-api-proxy.md#step-1-create-an-api-proxy). This opens the **Resources** pane, where you can define resources for the API proxy. -3. In the **Resources** pane, follow the steps given below to add resources: - - - Select **GET** as the **HTTP Verb**, enter `/users` as the **URI Pattern**, and click **+** to add the resource. - - Select **GET** as the **HTTP Verb**, enter `/users/{userID}` as the **URI Pattern**, and click **+** to add the resource. - - Select **POST** as the **HTTP Verb**, enter `/users` as the **URI Pattern**, and click **+** to add the resource. - - Select **DELETE** as the **HTTP Verb**, enter `/users/{userID}` as the **URI Pattern**, and click **+** to add the resource. - -4. To remove the five default resources that start with `/*`, click the delete icon corresponding to each resource. This marks the resources for deletion. -5. Click **Save**. The API resources will be as follows: - - ![API resources](../assets/img/tutorials/role-based-auth/api-resources.png) - -6. In the left navigation menu, click **Deploy**. -7. Go to the **Build Area** card and click **Configure & Deploy**. -8. In the **Configure API Access Mode** pane that opens, select either **External** or **Internal**, depending on how you want the API to be accessible. In this tutorial, select **External**. -9. Click **Deploy**. - -### Step 2: Apply permission to resources and publish the API - -Follow these steps: - -1. On the **Deploy** page, go to the **Build Area** card and click **Security Settings**. -2. In the **Security Settings** pane, go to the **Permissions List** section and click **+ Add Permission(Scope)**. -3. To add necessary permission values to the permission list, follow the steps given below: - 1. In the **Permissions List** section, enter `get_user_list` as the permission value and click **+Add New**. - 2. Similarly, add `get_user`, `create_user`, and `delete_user` as permission values. -4. In the **Permissions** section, expand each resource and select the permission values as follows for each: - - | **Resource** | **Permission** | - |---------------------------|----------------| - | **GET/users** | `get_user_list`| - | **GET/users/{userID}** | `get_user` | - | **POST/users** | `create_user` | - | **DELETE/users/{userID}** | `delete_user` | - -5. Click **Apply**. -6. To apply the latest permissions to the deployed component, you must redeploy it. Follow the steps below to redeploy: - 1. Go to the **Build Area** card and click **Configure & Deploy**. - 2. In the **Configure API Access Mode** pane that opens, select either **External** or **Internal**, depending on how you want the API to be accessible. In this tutorial, select **External**. - 3. Click **Deploy**. - -Now you are ready to promote the API to production. - -6. In the left navigation menu, click **Deploy**. -7. Go to the **Development** card and click **Promote**. The **Configure & Deploy** pane opens with the **Use Development endpoint configuration** option selected by default. -8. Click **Next** to promote the API to production. Now you can publish the API -9. In the left navigation menu, click **Manage** and then click **Lifecycle**. -10. In the **Lifecycle Management** pane, click **Publish**. This changes the status of the API to **Published**. - -Now, an application developer can discover the API, subscribe to it and then invoke it. - -### Step 3: Subscribe to the Published API - -In this step, you take the role of an application developer who consumes the published API. -To consume the API, you must create an application, generate keys, and subscribe to the API. - -Follow these steps: - -1. Go to the [API Developer Portal](https://devportal.choreo.dev/) and click **Applications** on the top menu. -2. Click **+Create**. -3. Enter `User Management App` as the **Application Name** and click **Create**. This creates the application and takes you to the application overview page. -4. In the Developer Portal left navigation menu, click **Production** under **Credentials**. -5. Click to expand **Advanced Configurations** and follow these steps to generate credentials for the application: - 1. Select **Code** as the grant type. - 2. Enter the hosted URL of the application as the **Callback URL**. - 3. Click **Generate Credentials**. -6. To subscribe to the API follow these steps: - 1. In the Developer Portal left navigation menu, click **Subscriptions**. - 2. In the **Subscription Management** pane, click **Add APIs**. - 3. In the **Add APIs** list, go to the API you created, and click **Add**. - -### Step 4: Define roles and assign them to groups - -In this step, you define roles, create necessary groups and assign appropriate roles to groups so that you can easily manage user permission. - -Follow these steps: - -1. In the Developer Portal left navigation menu, click **Production** under **Credentials**. -2. In the **Permissions** section, click **Manage Permissions**. This takes you to the **Roles** tab of the `User Management App` application in Asgardeo, where you can add applicable roles. - - ![Manage permissions](../assets/img/tutorials/role-based-auth/manage-permission.png) - -3. Follow these steps to add roles: - 1. Click **+ New Role**, enter `admin` as the **Role Name**, and click **Next**. - 2. Select `get_user_list`, `get_user`, `create_user`, and `delete_user`as **Role Permissions**. - 3. Click **Finish**. - 4. Similarly, add another role with `user` as the **Role Name** and `get_user_list`, and `get_user` as **Role Permissions**. - - Now you can proceed to create groups and assign applicable roles to the groups. - -4. In the Asgardeo Console left navigation menu, click **User Management** and then click **Groups**. -5. In the **Groups** pane, follow these steps to add groups and assign roles: - 1. Click **+ New Group**, enter `HR-Manager` as the **Group Name**, and click **Finish**. - 2. Click the **Roles** tab in the HR-Manager group you created and then click **+ Assign Roles**. - 3. Click the arrow corresponding to the User Management App to view applicable roles and select **admin**. - 4. Click **Save**. - 5. Similarly, add another group with `HR-Officer` as the **Group Name** and assign the **user** role to it. - - -### Step 5: Define users and assign them to groups - -In this step, you define users and assign them to groups depending on the job function of the user. This allows you to manage permission at the group level instead of for individual users. - -Follow these steps: - -1. Define two users named `Cameron` and `Alex`. For step-by-step instructions on adding a user, see [Manage users](https://wso2.com/asgardeo/docs/guides/users/manage-customers/#onboard-a-user) in the Asgardeo documentation. -2. Assign `Cameron` to the **HR-Manager** group and assign `Alex` to the **HR-Officer** group. For step-by-step instructions on assigning a user to a group, see [Assign groups](https://wso2.com/asgardeo/docs/guides/users/manage-customers/#assign-groups) in the Asgardeo documentation. - -### Step 6: Obtain an access token and try out the API - -Follow these steps: - -1. Construct the authorization URL as follows by replacing the placeholders with appropriate values: - - ``` - ?response_type=code&client_id=&redirect_uri=&scope= - ``` - - - Replace `` with the URL populated as the **Authorize Endpoint** in the **Application Keys** pane. - - ![Authorize endpoint](../assets/img/tutorials/role-based-auth/authorize-endpoint.png){.cInlineImage-full} - - - Replace `` with the value specified as the **Callback URL** under **Advanced Configurations** in the **Application Keys** pane. - - ![Callback URL](../assets/img/tutorials/role-based-auth/callback-url.png){.cInlineImage-full} - - - Replace `` with the permission(scopes) applicable to the user. You can copy the applicable permission(scopes) from the **API Overview** page. Here let’s copy the permission(scopes) applicable to the user `Alex`. - - ![Scopes](../assets/img/tutorials/role-based-auth/scopes.png){.cInlineImage-full} - - - Replace `` with the value populated as **Consumer Key** in the **Application Keys** pane. - - ![Consumer key](../assets/img/tutorials/role-based-auth/consumer-key.png){.cInlineImage-full} - -2. Open the constructed URL via a web browser. This will take you to a sign-in page provided by Asgardeo. - -3. Sign in with credentials of `Alex` and click **Allow** to approve the consent. - - ![Approve consent](../assets/img/tutorials/role-based-auth/consent.png){.cInlineImage-small} - - This redirects you to the callback URL of the application. The URL includes a code as a query parameter. - - ![Code](../assets/img/tutorials/role-based-auth/code.png){.cInlineImage-half} - -4. Copy the code and use it to replace `` in the following cURL command to invoke the authorization code grant token request: - - ``` - curl -d "grant_type=authorization_code&code=&redirect_uri=" -H "Authorization: Basic " - ``` - - - Replace `` with the URL populated as the **Token Endpoint** in the **Application Keys** pane. - - ![Token endpoint](../assets/img/tutorials/role-based-auth/token-endpoint.png){.cInlineImage-full} - - - Replace `` with the value specified as the **Callback URL** under **Advanced Configurations** in the **Application Keys** pane. - - - Use a Base64 encoder to encode your client ID and client secret in the following format and replace `` with the encoded value: - - **`:`** - - !!!note - - WSO2 does not recommend the use of online Base64 encoders for this purpose. - -5. Extract the access token from the response that you get. - - ![Access token](../assets/img/tutorials/role-based-auth/access-token.png){.cInlineImage-full} - -6. Go to the [API Developer Portal](https://devportal.choreo.dev/), try out the HR API using the access token you extracted, and observe the responses. - - You’ll observe that it is only possible to access the following resources because the access token only contains the permission(scopes) to invoke those resources: - - - GET /users - - GET /users/{userID} - - Invoking any other resource gives you a scope validation failed response because the token doesn't include the required scopes to invoke them. - ![Scope validation failed](../assets/img/tutorials/role-based-auth/scope-validation-failed.png){.cInlineImage-full} - - Similarly, if you use Cameron’s credentials and sign in to obtain an access token, you'll observe that you can invoke all four resources because it would contain all the required permission(scopes). - -Now you have gained hands-on experience in implementing role-based access control with Choreo and Asgardeo. diff --git a/en/docs/what-is-choreo.md b/en/docs/what-is-choreo.md deleted file mode 100644 index 923552828..000000000 --- a/en/docs/what-is-choreo.md +++ /dev/null @@ -1,37 +0,0 @@ -# What is Choreo? - -Choreo is an internal developer platform that redefines how you create digital experiences. Choreo empowers you to seamlessly design, develop, deploy, and govern your cloud native applications, unlocking innovation while reducing time-to-market. - -The following are some of the cutting-edge capabilities of Choreo: - - - Design that leads to end-to-end security, governance, and operational efficiency: - - **Domain-driven design**: Organize your enterprise systems into domains, exposing managed APIs, events, and data through projects., A project consists of components representing units of deployment. - - **Application security design**: [Cell-based architecture](https://github.com/wso2/reference-architecture/blob/master/reference-architecture-cell-based.md), where projects become governable units from development to deployment, ensuring managed access via APIs, events, and data. - - - Efficient and effective development: - - **Code in any language**: Develop applications in your team's preferred programming language, harnessing existing skill sets to build powerful polyglot APIs, services, events, tasks, and more. - - **Native support for VS Code**: Seamlessly collaborate and manage code using VS Code in a feature-rich, visually-enhanced development environment. - - **Git repository integration**: Effortlessly connect to Git-based platforms like GitHub, Bitbucket, or GitLab to develop components by linking an existing repository. - - - Seamless deployment: - - **CI/CD**: Eliminate manual builds and unreliable deployments with Choreo's industry-standard CI/CD tooling, providing complete control and flexibility. - - **Multi-cloud Kubernetes**: Easily deliver cloud native applications across Azure, AWS, GCP, or your Kubernetes clusters. - - **Configuration management**: Centralize configuration parameters, sensitive credentials, and secrets across deployment environments via an intuitive interface. - - - Effortless management of APIs, integrations, microservices, and web applications: - - **Enable security**: Empower security teams to manage data flows, ensuring seamless control over sensitive information like access credentials. - - **Scale up or down**: Kubernetes handles scaling automatically, optimizing costs by scaling services based on demand. - - **Ensure reliability**: DevOps and SRE teams can easily manage deployed components with built-in insights and observability. - - - Reusable digital assets: - - **Control visibility and sharing**: Publish your digital assets to a shared marketplace for consumption by internal or external stakeholders, managed by role-based access control. - - **Internal Marketplace**: Choreo's secure internal marketplace fosters transparency and efficiency with granular access control for publishers and consumers. - - - Comprehensive observability: - - **Anomaly detection**: Stay ahead of issues with prompt notifications, ensuring balanced scaling and immediate action during unexpected mishaps. - - **Troubleshoot and debug**: Quickly pinpoint and address root causes using detailed logs and data aligned in the same timeline, down to the machine-level details. - - - Robust governance: - - **DORA metrics**: Monitor your DevOps efficiency with Choreo DORA metrics, experiencing rapid improvements in time from deployment to production safely and robustly. - - **Engineering insights**: Gain visibility into engineering insights and advanced data analytics to make data-driven decisions, optimize processes, and improve efficiency. - - **API analytics**: Understand API performance and adoption patterns to identify and resolve operational bottlenecks. diff --git a/en/mkdocs.yml b/en/mkdocs.yml deleted file mode 100644 index 2bc877e34..000000000 --- a/en/mkdocs.yml +++ /dev/null @@ -1,442 +0,0 @@ -# Copyright (c) 2021, WSO2 Inc. (http://www.wso2.org) All Rights Reserved. -# -# WSO2 Inc. licenses this file to you under the Apache License, -# Version 2.0 (the "License"); you may not use this file except -# in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, -# software distributed under the License is distributed on an -# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY -# KIND, either express or implied. See the License for the -# specific language governing permissions and limitations -# under the License. - -# Project information -site_name: "" -site_description: Choreo Learning Portal -site_author: WSO2 -site_url: https://wso2.com/choreo/docs - -# Repository -repo_name: wso2/docs-choreo-dev -repo_url: https://github.com/wso2/docs-choreo-dev/ -edit_uri: https://github.com/wso2/docs-choreo-dev/edit/dev/en/docs/ -dev_addr: localhost:8000 - -# Copyright -copyright: ©2023 WSO2 LLC. - -# Configuration -theme: - name: material - custom_dir: theme/material - logo: assets/images/logo.png - font: - text: Montserrat - favicon: assets/images/favicon.png - features: - - navigation.expand - - navigation.path - - navigation.top - - content.code.copy - - content.action.edit - - content.action.view - language: 'en' - palette: - # Palette toggle for automatic mode - - media: "(prefers-color-scheme)" - toggle: - icon: material/brightness-auto - name: Switch to dark mode - - # Palette toggle for light mode - - media: "(prefers-color-scheme: light)" - scheme: default - toggle: - icon: material/brightness-7 - name: Switch to system preference - - # Palette toggle for dark mode - - media: "(prefers-color-scheme: dark)" - scheme: slate - toggle: - icon: material/brightness-4 - name: Switch to light mode - icon: - logo: logo -#Breaks build if there's a warning -strict: false -# Navigation -nav: - - Home: index.md - - Introduction: - - What is Choreo?: what-is-choreo.md - - Quick Start Guides: - - Deploy Your First Service: quick-start-guides/deploy-your-first-service.md - - Deploy Your First Static Web Application: quick-start-guides/deploy-your-first-static-web-application.md - - Deploy a Web Application that Consumes a Backend Service: quick-start-guides/deploy-a-web-application-that-consumes-a-backend-service.md - - Choreo Samples: - - Explore the Samples Collection: - - Samples Overview: choreo-samples/samples-overview.md - - Quick Deploy a Sample: choreo-samples/quick-deploy-a-sample.md - - Explore the Demo Organization: choreo-samples/explore-the-demo-organization.md - - Tutorials: - - Expose a Service as a Managed API: tutorials/expose-a-service-as-a-managed-api.md - - Secure an API with Role-Based Access Control: tutorials/secure-an-api-with-role-based-access-control.md - - Choreo Concepts: - - Resource Hierarchy: choreo-concepts/resource-hierarchy.md - - Organization: choreo-concepts/organization.md - - Project: choreo-concepts/project.md - - Component: choreo-concepts/component.md - - Endpoint: choreo-concepts/endpoint.md - - CI/CD: choreo-concepts/ci-cd.md - - Deployment Tracks: choreo-concepts/deployment-tracks.md - - Connections: choreo-concepts/connections.md - - Data Planes: choreo-concepts/data-planes.md - - Environments: choreo-concepts/environments.md - - Choreo Marketplace: choreo-concepts/choreo-marketplace.md - - Develop Components: - - Develop Services: - - Service Component Overview: develop-components/develop-services/service-component-overview.md - - Develop a Service: develop-components/develop-services/develop-a-service.md - - Develop a service with Docker: develop-components/develop-services/develop-a-service-with-docker.md - - Develop a Ballerina Service: develop-components/develop-services/develop-a-ballerina-service.md - - Expose a gRPC Endpoint via a Service: develop-components/develop-services/expose-a-grpc-endpoint-via-a-service.md - - Expose a TCP Server via a Service: develop-components/develop-services/expose-a-tcp-server-via-a-service.md - - Expose a UDP Server via a Service: develop-components/develop-services/expose-a-udp-server-via-a-service.md - - Expose a Ballerina GraphQL Endpoint via a Service: develop-components/develop-services/expose-a-ballerina-graphql-endpoint-via-a-service.md - - Expose a Prism-Based Mock Server Using an OpenAPI Specification: develop-components/develop-services/expose-a-prism-based-mock-server-using-an-openapi-specification.md - - Expose a WebSocket Endpoint via a Service: develop-components/develop-services/expose-a-websocket-endpoint-via-a-service.md - - Develop an API Proxy: develop-components/develop-an-api-proxy.md - - Develop Web Applications: - - Build and Deploy a Single-Page Web Application: develop-components/develop-web-applications/build-and-deploy-a-single-page-web-application.md - - Develop Web Applications Locally with Choreo’s Managed Authentication: develop-components/develop-web-applications/develop-web-applications-locally-with-managed-authentication.md - - Develop a Webhook: develop-components/develop-a-webhook.md - - Develop an External Consumer: develop-components/develop-an-external-consumer.md - - Develop Integrations: - - Develop an Integration with Integration Studio: develop-components/develop-integrations/develop-an-integration-with-integration-studio.md - - Develop an Event Handler: develop-components/develop-integrations/develop-an-event-handler.md - - Develop a Scheduled Task: develop-components/develop-integrations/develop-a-scheduled-task.md - - Develop a Manual Task: develop-components/develop-integrations/develop-a-manual-task.md - - Work with the Micro Integrator Runtime: - - Get Started with the Micro Integrator Runtime: develop-components/work-with-the-micro-integrator-runtime-in-choreo.md - - Manage the Micro Integrator Runtime Version in Your Integration Project: develop-components/manage-the-micro-integrator-runtime-version-in-your-integration-project.md - - Develop Components With Git: develop-components/develop-components-with-git.md - - Bring Your Own Image: develop-components/bring-your-own-image.md - - Deploy an Application with Buildpacks: develop-components/deploy-an-application-with-buildpacks.md - - Deploy a Containerized Application: develop-components/deploy-a-containerized-application.md - - Share and Reuse Components: - - Create a Connection: develop-components/sharing-and-reusing/create-a-connection.md - - Use a Connection in Your Service: develop-components/sharing-and-reusing/use-a-connection-in-your-service.md - - Use a Connection in Your Web Application: develop-components/sharing-and-reusing/use-a-connection-in-your-web-application.md - - Use a Database Connection in Your Component: develop-components/sharing-and-reusing/use-a-database-connection-in-your-component.md - - Manage Deployment Tracks for Choreo Components: develop-components/manage-deployment-tracks-for-choreo-components.md - - Configure Endpoints: develop-components/configure-endpoints.md - - Manage Component Source Configurations: develop-components/manage-component-source-configurations.md - - Submit and Manage Workflow Approval Requests: develop-components/submit-and-manage-workflow-approval-requests.md - - Develop Components Using VS Code: develop-components/develop-components-using-vs-code.md - - Integrate and Manage External Services: - - Integrate and Manage Third-Party Services: integrate-and-manage-external-services/integrate-and-manage-third-party-services.md - - Integrate and Manage Generative AI Services: integrate-and-manage-external-services/integrate-and-manage-gen-ai-services.md - - Choreo-Managed Databases and Caches: - - Overview: manage-databases-and-caches/choreo-managed-databases-and-caches.md - - PostgreSQL: manage-databases-and-caches/choreo-managed-postgresql-databases.md - - MySQL: manage-databases-and-caches/choreo-managed-mysql-databases.md - - Choreo-Managed Cache: manage-databases-and-caches/choreo-managed-caches.md - - Add Choreo-Managed Databases and Caches to the Marketplace: manage-databases-and-caches/add-choreo-managed-databases-and-caches-to-the-marketplace.md - - Choreo-Managed Message Brokers: - - Overview: manage-message-brokers/choreo-managed-message-brokers.md - - Kafka: - - Create Choreo-Managed Kafka Services: manage-message-brokers/create-choreo-managed-kafka-services.md - - Configure a Kafka Service: manage-message-brokers/configure-a-kafka-service.md - - Monitor a Kafka Service: manage-message-brokers/monitor-a-kafka-service.md - - Authentication and Authorization: - - Secure API Access with Asgardeo: authentication-and-authorization/secure-api-access-with-asgardeo.md - - Secure API Access with Azure: authentication-and-authorization/secure-api-access-with-azure-ad.md - - Secure Web Applications with Managed Authentication: authentication-and-authorization/secure-web-applications-with-managed-authentication.md - - Test Secure API Access with Choreo Built-In Security Token Service: authentication-and-authorization/test-secure-api-access-with-choreo-built-in-security-token-service.md - - Pass End-User Attributes to Upstream Services: authentication-and-authorization/pass-end-user-attributes-to-upstream-services.md - - Configure Mutual TLS Between Components: authentication-and-authorization/configure-mutual-tls-between-components.md - - Secure Communication Between the Choreo Gateway and Your Backend with Mutual TLS: authentication-and-authorization/secure-communication-between-the-choreo-gateway-and-your-backend-with-mutual-tls.md - - DevOps and CI/CD: - - Manage Configurations and Secrets: devops-and-ci-cd/manage-configurations-and-secrets.md - - View Runtime Details: devops-and-ci-cd/view-runtime-details.md - - Configure Container Resources, Commands, and Arguments: devops-and-ci-cd/configure-container-resources-commands-and-arguments.md - - Set Up Health Checks: devops-and-ci-cd/set-up-health-checks.md - - Autoscale: - - Autoscale Component Replicas: devops-and-ci-cd/autoscale/autoscale-component-replicas.md - - Autoscale Components with Scale-to-Zero: devops-and-ci-cd/autoscale/autoscale-components-with-scale-to-zero.md - - Configure Storage: devops-and-ci-cd/configure-storage.md - - Manage Environments: devops-and-ci-cd/manage-environments.md - - Configure VPNs on the Choreo Cloud Data Plane: devops-and-ci-cd/configure-vpns-on-the-choreo-cloud-data-plane.md - - Testing: - - Test REST Endpoints via the OpenAPI Console: testing/test-rest-endpoints-via-the-openapi-console.md - - Test GraphQL Endpoints via the GraphQL Console: testing/test-graphql-endpoints-via-the-graphql-console.md - - Test WebSocket Endpoints via the WebSocket Console: testing/test-websocket-endpoints-via-the-websocket-console.md - - Test APIs with cURL: testing/test-apis-with-curl.md - - Test APIs with Choreo API Chat: testing/test-apis-with-choreo-apichat.md - - Test Components with Test Runner: testing/test-components-with-test-runner.md - - Consuming Services: - - Consume a Service: consuming-services/consuming-a-sevice.md - - Manage Application: consuming-services/manage-application.md - - Share Applications: consuming-services/share-applications.md - - Manage Subscription: consuming-services/manage-subscription.md - - Generate an Access Token: consuming-services/generate-an-access-token.md - - API Management: - - Lifecycle Management: api-management/lifecycle-management.md - - Documents: api-management/documents.md - - API Rate Limiting: api-management/api-rate-limiting.md - - API Policies: - - About API Policies: api-management/api-policies/about-api-policies.md - - Attach and Manage Policies: api-management/api-policies/attach-and-manage-policies.md - - Apply Advanced Settings on Mediation Policies: api-management/api-policies/apply-advanced-settings-on-mediation-policies.md - - Control API Visibility: api-management/control-api-visibility.md - - Manage API Traffic: - - Assign Subscription Plans to APIs: api-management/manage-api-traffic/assign-subscription-plans-to-apis.md - - Subscribe to an API with a Subscription Plan: api-management/manage-api-traffic/subscribe-to-an-api-with-a-subscription-plan.md - - Rename API Display Name: api-management/rename-api-display-name.md - - Monitoring and Insights: - - Observability Overview: monitoring-and-insights/observability-overview.md - - Delivery Insights: - - Configure DORA Metrics: monitoring-and-insights/delivery-insights/configure-dora-metrics.md - - View DORA Metrics: monitoring-and-insights/delivery-insights/view-dora-metrics.md - - Usage Insights: - - Insights Overview: monitoring-and-insights/insights-overview.md - - Configure Alerts: monitoring-and-insights/alerts/configure-alerts.md - - Generate Custom Reports: monitoring-and-insights/generate-custom-reports.md - - View Logs: monitoring-and-insights/view-logs.md - - Work with the Choreo Insights API: - - Access the Choreo Insights API: monitoring-and-insights/work-with-choreo-insights-api/access-the-choreo-insights-api.md - - Choreo Insights API: monitoring-and-insights/work-with-choreo-insights-api/choreo-insights-api.md - - Integrate Choreo with Moesif: monitoring-and-insights/integrate-choreo-with-moesif.md - - Choreo CLI: - - Choreo CLI Overview: choreo-cli/choreo-cli-overview.md - - Get Started with the Choreo CLI: choreo-cli/get-started-with-the-choreo-cli.md - - Manage Authentication with Personal Access Tokens: choreo-cli/manage-authentication-with-personal-access-tokens.md - - Administer: - - Control Access in the Choreo Console: administer/control-access-in-the-choreo-console.md - - Configure a Custom Domain for Your Organization: administer/configure-a-custom-domain-for-your-organization.md - - Configure Enterprise Login: administer/configure-enterprise-login.md - - Configure an External IdP: - - Configure Asgardeo as an External IdP: administer/configure-an-external-idp/configure-asgardeo-as-an-external-idp.md - - Configure Azure as an External IdP: administer/configure-an-external-idp/configure-azure-ad-as-an-external-idp.md - - Create API Subscription Plans: administer/create-api-subscription-plans.md - - Configure Approvals for Choreo Workflows: administer/configure-approvals-for-choreo-workflows.md - - Review Workflow Approval Requests: administer/review-workflow-approval-requests.md - - Configure a User Store with the Built-In Identity Provider: administer/configure-a-user-store-with-built-in-idp.md - - Developer Portal: - - Customize the Developer Portal: administer/customize-the-developer-portal.md - - Configure Self-Sign-Up: administer/configure-self-sign-up.md - - Manage Members of an Organization: administer/manage-members-of-an-organization.md - - Control Egress Traffic for Your Organization: administer/control-egress-traffic-for-your-organization.md - - References: - - FAQ: references/faq.md - - Choreo Limitations: references/choreo-limitations.md - - Troubleshoot Choreo: references/troubleshoot-choreo.md - - Private Data Plane Security Levels: references/private-data-plane-security-levels.md - - Private Data Plane Management Models: references/private-data-plane-management-models.md - - Choreo Platform Service Billing and Upgrades: references/choreo-platform-services-billing-and-upgrades.md - -# Extensions -# Extensions -markdown_extensions: - - markdown.extensions.admonition - - markdown.extensions.def_list - - markdown.extensions.footnotes - - markdown.extensions.toc: - permalink: true - toc_depth: 3 - - pymdownx.arithmatex - - pymdownx.betterem: - smart_enable: all - - pymdownx.caret - - pymdownx.critic - - pymdownx.details - - pymdownx.emoji: - emoji_generator: !!python/name:pymdownx.emoji.to_svg - - pymdownx.highlight: - anchor_linenums: true - pygments_lang_class: true - - pymdownx.keys - - pymdownx.mark - - pymdownx.smartsymbols - - pymdownx.superfences - - pymdownx.tabbed: - alternate_style: true - - pymdownx.tasklist: - custom_checkbox: true - - pymdownx.tilde - - pymdownx.snippets: - base_path: docs - - attr_list -plugins: - - search - - include-markdown - - glightbox - - open-in-new-tab - - markdownextradata: {} - - redirects: - redirect_maps: - 'tutorials/create-your-first-rest-api.md': 'https://wso2.com/choreo/docs/get-started/tutorials/create-your-first-rest-api/' - 'tutorials/connect-your-own-github-repository-to-choreo.md': 'https://wso2.com/choreo/docs/manage-repository/connect-your-own-github-repository-to-choreo/' - 'tutorials/construct-statements.md': 'https://wso2.com/choreo/docs/develop/explore-code-editor/construct-statements/' - 'tutorials/connect-your-existing-ballerina-project-to-choreo.md': 'https://wso2.com/choreo/docs/manage-repository/connect-your-existing-ballerina-project-to-choreo/' - 'tutorials/configure-automatic-deployment.md': 'https://wso2.com/choreo/docs/deploy/configure-automatic-deployment/' - 'tutorials/map-data.md': 'https://wso2.com/choreo/docs/develop/explore-code-editor/map-data/' - 'rest-api.md': 'https://wso2.com/choreo/docs/develop/components/rest-api/' - 'api-proxies.md': 'https://wso2.com/choreo/docs/develop/components/api-proxy/' - 'api-proxies/api-proxy.md': 'https://wso2.com/choreo/docs/develop/components/api-proxy/' - 'webhook.md': 'https://wso2.com/choreo/docs/develop/components/webhook/' - 'scheduled-tasks.md': 'https://wso2.com/choreo/docs/develop/components/scheduled-trigger/' - 'manual-triggers.md': 'https://wso2.com/choreo/docs/develop/components/manual-trigger/' - 'graphql-api.md': 'https://wso2.com/choreo/docs/develop/components/graphql-api/' - 'developer-portal/developer-portal.md': 'https://wso2.com/choreo/docs/consume/developer-portal/' - 'developer-portal/manage-application.md': 'https://wso2.com/choreo/docs/consume/manage-application/' - 'developer-portal/manage-subscription.md': 'https://wso2.com/choreo/docs/consume/manage-subscription/' - 'developer-portal/test-api.md': 'https://wso2.com/choreo/docs/consume/test-api/' - 'insights/view-api-insights.md': 'https://wso2.com/choreo/docs/observe-and-analyze/analyze/view-api-insights/' - 'insights/generate-custom-reports.md': 'https://wso2.com/choreo/docs/observe-and-analyze/analyze/generate-custom-reports/' - 'insights/configure-alerts.md': 'https://wso2.com/choreo/docs/observe-and-analyze/analyze/configure-alerts/' - 'insights/choreo-insights-api.md': 'https://wso2.com/choreo/docs/observe-and-analyze/analyze/choreo-insights-api/' - 'insights/programmatic-access-choreo-insights-api.md': 'https://wso2.com/choreo/docs/observe-and-analyze/analyze/programmatic-access-choreo-insights-api/' - 'administration/connect-to-an-external-identity-provider.md': 'https://wso2.com/choreo/docs/administer/connect-to-an-external-identity-provider/' - 'administration/customize-developer-portal-domain.md': 'https://wso2.com/choreo/docs/administer/customize-developer-portal-domain/' - 'administration/configure-a-custom-domain-for-apis.md': 'https://wso2.com/choreo/docs/administer/configure-a-custom-domain-for-apis/' - 'administration/customize-the-developer-portal.md': 'https://wso2.com/choreo/docs/administer/customize-the-developer-portal/' - 'administration/configure-enterprise-login.md': 'https://wso2.com/choreo/docs/administer/configure-enterprise-login/' - 'administration/configure-developer-portal-self-sign-up.md': 'https://wso2.com/choreo/docs/administer/configure-developer-portal-self-sign-up/' - 'observability/observability-overview.md': 'https://wso2.com/choreo/docs/observe-and-analyze/observe/observability-overview/' - 'observability/root-cause-analysis.md': 'https://wso2.com/choreo/docs/observe-and-analyze/observe/root-cause-analysis/' - 'references/performance-analysis.md': 'https://wso2.com/choreo/docs/develop/run-and-test/forecast-performance-metrics/' - 'references/alerting.md': 'https://wso2.com/choreo/docs/alerts/' - 'references/manage-connectors.md': 'https://wso2.com/choreo/docs/develop/advanced-topics/manage-connectors/' - 'references/handle-non-ballerina-files-in-choreo.md': 'https://wso2.com/choreo/docs/develop/explore-code-editor/handle-non-ballerina-files-in-choreo/' - 'references/define-configurable-variables.md': 'https://wso2.com/choreo/docs/develop/explore-code-editor/define-configurable-variables/' - 'references/connect-with-protected-third-party-applications.md': 'https://wso2.com/choreo/docs/references/connect-with-protected-third-party-applications/' - 'develop/components/api-proxies/policies.md': 'https://wso2.com/choreo/docs/develop/api-policies/policies/' - 'get-started/what-is-choreo.md': 'https://wso2.com/choreo/docs/what-is-choreo/' - 'get-started/quick-start-guide.md': 'https://wso2.com/choreo/docs/quick-start-guides/build-your-first-cloud-native-application-with-choreo/' - 'get-started/build-your-first-cloud-native-application-with-choreo.md': 'https://wso2.com/choreo/docs/quick-start-guides/deploy-a-web-application-that-consumes-a-backend-service/' - 'get-started/tutorials/create-your-first-rest-api.md': 'https://wso2.com/choreo/docs/quick-start-guides/build-your-first-cloud-native-application-with-choreo/' - 'get-started/tutorials/create-your-first-rest-api-proxy.md': 'https://wso2.com/choreo/docs/quick-start-guides/expose-a-service-as-a-managed-api-with-choreo-api-manager/' - 'get-started/tutorials/create-your-first-webhook.md': 'https://wso2.com/choreo/docs/develop-components/develop-a-webhook/' - 'get-started/tutorials/create-your-first-integration-as-an-api.md': 'https://wso2.com/choreo/docs/quick-start-guides/build-your-first-integration-with-choreo-ipaas/' - 'get-started/tutorials/create-your-first-event-triggered-integration.md': 'https://wso2.com/choreo/docs/develop-components/develop-integrations/develop-an-event-triggered-integration/' - 'get-started/tutorials/secure-an-api-with-role-based-access-control.md': 'https://wso2.com/choreo/docs/tutorials/secure-an-api-with-role-based-access-control/' - 'get-started/tutorials/create-your-first-containerized-service-component.md': 'https://wso2.com/choreo/docs' - 'get-started/tutorials/deploy-a-containerized-application-as-an-event-triggered-integration.md': 'https://wso2.com/choreo/docs/develop-components/deploy-a-containerized-application/' - 'develop/components/rest-api.md': 'https://wso2.com/choreo/docs/develop-components/develop-services/develop-a-rest-api/' - 'develop/components/api-proxy.md': 'https://wso2.com/choreo/docs/develop-components/develop-a-rest-api-proxy/' - 'develop/components/webhook.md': 'https://wso2.com/choreo/docs/develop-components/develop-a-webhook/' - 'develop/components/scheduled-trigger.md': 'https://wso2.com/choreo/docs/develop-components/develop-integrations/develop-a-scheduled-integration/' - 'develop/components/manual-trigger.md': 'https://wso2.com/choreo/docs' - 'develop/components/graphql-api.md': 'https://wso2.com/choreo/docs/develop-components/develop-services/develop-a-ballerina-graphql-api/' - 'develop/components/service.md': 'https://wso2.com/choreo/docs/develop-components/develop-services/develop-a-service/' - 'develop/manage-repository/connect-your-own-github-repository-to-choreo.md': 'https://wso2.com/choreo/docs/develop-components/develop-components-with-git/' - 'develop/run-and-test/forecast-performance-metrics.md': 'https://wso2.com/choreo/docs' - 'develop/api-policies/policies.md': 'https://wso2.com/choreo/docs/api-management/api-policies/' - 'develop/api-policies/create-a-policy.md': 'https://wso2.com/choreo/docs/api-management/api-policies/' - 'develop/api-policies/attach-policies.md': 'https://wso2.com/choreo/docs/api-management/api-policies/' - 'deploy/deploy-a-ballerina-application.md': 'https://wso2.com/choreo/docs' - 'deploy/deploy-a-containerized-application.md': 'https://wso2.com/choreo/docs/develop-components/deploy-a-containerized-application/' - 'deploy/devops/runtime.md': 'https://wso2.com/choreo/docs/devops-and-ci-cd/view-runtime-details/' - 'deploy/devops/containers.md': 'https://wso2.com/choreo/docs/devops-and-ci-cd/configure-container-resources-commands-and-arguments/' - 'deploy/devops/configs-and-secrets.md': 'https://wso2.com/choreo/docs/devops-and-ci-cd/manage-configurations-and-secrets/' - 'deploy/devops/health-checks.md': 'https://wso2.com/choreo/docs/devops-and-ci-cd/set-up-health-checks/' - 'deploy/devops/scaling.md': 'https://wso2.com/choreo/docs/devops-and-ci-cd/autoscale-component-replicas/' - 'deploy/devops/storage.md': 'https://wso2.com/choreo/docs/devops-and-ci-cd/configure-storage/' - 'test/invoke-apis-via-console.md': 'https://wso2.com/choreo/docs/testing/test-rest-endpoints-via-the-openapi-console/' - 'test/open-api-console.md': 'https://wso2.com/choreo/docs/testing/test-rest-endpoints-via-the-openapi-console/' - 'test/curl.md': 'https://wso2.com/choreo/docs/devops-and-ci-cd/configure-storage/' - 'test/graphql-console.md': 'https://wso2.com/choreo/docs/testing/test-graphql-endpoints-via-the-graphql-console/' - 'manage/api-management.md': 'https://wso2.com/choreo/docs/api-management/lifecycle-management/' - 'manage/lifecycle.md': 'https://wso2.com/choreo/docs/api-management/lifecycle-management/' - 'manage/api-security/pass-end-user-attributes-to-the-backend.md': 'https://wso2.com/choreo/docs/api-management/api-rate-limiting/' - 'manage/api-rate-limiting.md': 'https://wso2.com/choreo/docs/api-management/api-rate-limiting/' - 'consume/developer-portal.md': 'https://wso2.com/choreo/docs' - 'consume/manage-application.md': 'https://wso2.com/choreo/docs/consuming-services/manage-application/' - 'consume/manage-subscription.md': 'https://wso2.com/choreo/docs/consuming-services/manage-subscription/' - 'consume/test-api.md': 'https://wso2.com/choreo/docs/testing/test-rest-endpoints-via-the-openapi-console/' - 'marketplace.md': 'https://wso2.com/choreo/docs/choreo-concepts/choreo-marketplace/' - 'observe-and-analyze/observe/observability-overview.md': 'https://wso2.com/choreo/docs/monitoring-and-insights/observability-overview/' - 'observe-and-analyze/observe/root-cause-analysis.md': 'https://wso2.com/choreo/docs' - 'observe-and-analyze/analyze/view-api-insights.md': 'https://wso2.com/choreo/docs/monitoring-and-insights/view-api-insights/' - 'observe-and-analyze/analyze/generate-custom-reports.md': 'https://wso2.com/choreo/docs/monitoring-and-insights/generate-custom-reports/' - 'observe-and-analyze/analyze/configure-alerts.md': 'https://wso2.com/choreo/docs/monitoring-and-insights/alerts/configure-alerts/' - 'observe-and-analyze/analyze/choreo-insights-api.md': 'https://wso2.com/choreo/docs/monitoring-and-insights/work-with-choreo-insights-api/choreo-insights-api/' - 'observe-and-analyze/analyze/programmatic-access-choreo-insights-api.md': 'https://wso2.com/choreo/docs/monitoring-and-insights/work-with-choreo-insights-api/access-the-choreo-insights-api/' - 'observe-and-analyze/analyze/dora-metrics/configure-cio-dashboard.md': 'https://wso2.com/choreo/docs/monitoring-and-insights/engineering-insights/configure-cio-dashboard/' - 'observe-and-analyze/analyze/dora-metrics/view-dora-metrics.md': 'https://wso2.com/choreo/docs/monitoring-and-insights/engineering-insights/view-dora-metrics/' - 'alerts.md': 'https://wso2.com/choreo/docs/monitoring-and-insights/alerts/configure-alerts/' - 'ipaas/get-started-with-choreo-ipaas.md': 'https://wso2.com/choreo/docs/quick-start-guides/build-your-first-integration-with-choreo-ipaas/' - 'ipaas/ballerina/develop-integrations-with-ballerina.md': 'https://wso2.com/choreo/docs/quick-start-guides/build-your-first-integration-with-choreo-ipaas/' - 'ipaas/ballerina/create-your-first-event-triggered-integration.md': 'https://wso2.com/choreo/docs/develop-integrations/develop-an-event-triggered-integration/' - 'ipaas/micro-integrator/develop-integrations-with-integration-studio.md': 'https://wso2.com/choreo/docs/develop-integrations/develop-an-integration-with-integration-studio/' - 'ipaas/micro-integrator/create-your-first-integration.md': 'https://wso2.com/choreo/docs/quick-start-guides/build-your-first-integration-with-choreo-ipaas/' - 'administer/connect-to-an-external-identity-provider.md': 'https://wso2.com/choreo/docs' - 'administer/configure-developer-portal-self-sign-up.md': 'https://wso2.com/choreo/docs/administer/configure-self-sign-up/' - 'administer/organization.md': 'https://wso2.com/choreo/docs/choreo-concepts/organization/' - 'reference/connect-with-protected-third-party-applications.md': 'https://wso2.com/choreo/docs/troubleshoot/faq/#q-how-can-i-connect-a-choreo-component-with-a-protected-third-party-application' - 'quick-start-guides/build-your-first-integration-with-choreo-ipaas.md': 'https://wso2.com/choreo/docs/tutorials/build-your-first-integration/' - 'quick-start-guides/expose-a-service-as-a-managed-api-with-choreo-api-manager.md': 'https://wso2.com/choreo/docs/tutorials/expose-a-service-as-a-managed-api/' - 'monitoring-and-insights/engineering-insights/configure-cio-dashboard.md': 'https://wso2.com/choreo/docs/monitoring-and-insights/delivery-insights/configure-dora-metrics/' - 'monitoring-and-insights/engineering-insights/view-dora-metrics.md': 'https://wso2.com/choreo/docs/monitoring-and-insights/delivery-insights/view-dora-metrics/' - 'monitoring-and-insights/view-api-insights.md': 'https://wso2.com/choreo/docs/monitoring-and-insights/usage-insights/' - 'devops-and-ci-cd/autoscale-component-replicas.md': 'https://wso2.com/choreo/docs/devops-and-ci-cd/autoscale/autoscale-component-replicas' - 'testing/test-apis-with-choreo-testgpt.md': 'https://wso2.com/choreo/docs/testing/test-apis-with-choreo-apichat/' - 'develop-integrations/develop-an-event-triggered-integration.md': 'https://wso2.com/choreo/docs/develop-components/develop-integrations/develop-an-event-handler/' - 'develop-integrations/develop-a-scheduled-integration.md': 'https://wso2.com/choreo/docs/develop-components/develop-integrations/develop-a-scheduled-task/' - 'develop-components/develop-a-rest-api-proxy.md': 'https://wso2.com/choreo/docs/develop-components/develop-an-api-proxy/' - 'devops-and-ci-cd/builds-and-deployments.md' : 'https://wso2.com/choreo/docs/choreo-concepts/ci-cd/' - 'troubleshoot/faq.md': 'https://wso2.com/choreo/docs/references/faq/' - 'develop-components/develop-services/develop-a-rest-api.md': 'https://wso2.com/choreo/docs/develop-components/develop-services/develop-a-service/' - 'develop-components/develop-services/develop-a-go-rest-api.md': 'https://wso2.com/choreo/docs/develop-components/develop-services/develop-a-service-with-docker/' - 'develop-components/develop-services/develop-a-grpc-service.md': 'https://wso2.com/choreo/docs/develop-components/develop-services/expose-a-grpc-endpoint-via-a-service/' - 'develop-components/develop-services/develop-a-tcp-service.md': 'https://wso2.com/choreo/docs/develop-components/develop-services/expose-a-tcp-server-via-a-service/' - 'develop-components/develop-services/develop-a-udp-service.md': 'https://wso2.com/choreo/docs/develop-components/develop-services/expose-a-udp-server-via-a-service/' - 'develop-components/develop-services/develop-a-ballerina-rest-api.md': 'https://wso2.com/choreo/docs/develop-components/develop-services/develop-a-ballerina-service/' - 'develop-components/develop-services/develop-a-ballerina-graphql-api.md': 'https://wso2.com/choreo/docs/develop-components/develop-services/expose-a-ballerina-graphql-endpoint-via-a-service/' - 'quick-start-guides/build-your-first-cloud-native-application-with-choreo.md': 'https://wso2.com/choreo/docs/quick-start-guides/deploy-a-web-application-that-consumes-a-backend-service/' - 'choreo-concepts/configuration-management.md': 'https://wso2.com/choreo/docs/devops-and-ci-cd/manage-configurations-and-secrets/' - 'develop-components/develop-a-web-application.md': 'https://wso2.com/choreo/docs/develop-components/develop-web-applications/build-and-deploy-a-single-page-web-application/' - 'administer/configure-a-custom-domain-for-apis.md': 'https://wso2.com/choreo/docs/administer/configure-a-custom-domain-for-your-organization/' - 'administer/customize-developer-portal-domain.md': 'https://wso2.com/choreo/docs/administer/configure-a-custom-domain-for-your-organization/' - 'authentication-and-authorization/access-control/control-access-in-the-choreo-console.md': 'https://wso2.com/choreo/docs/administer/control-access-in-the-choreo-console/' - 'authentication-and-authorization/secure-communication-between-the-choreo-gateway-and-your-backend.md': 'https://wso2.com/choreo/docs/authentication-and-authorization/secure-communication-between-the-choreo-gateway-and-your-backend-with-mutual-tls/' - 'develop-components/sharing-and-reusing/share-and-reuse-services.md': 'https://wso2.com/choreo/docs/develop-components/sharing-and-reusing/use-a-connection-in-your-service/' - 'develop-components/sharing-and-reusing/share-and-reuse-web-applications.md': 'https://wso2.com/choreo/docs/develop-components/sharing-and-reusing/use-a-connection-in-your-web-application/' - 'manage-databases-and-caches/choreo-managed-redis-datastores.md': 'https://wso2.com/choreo/docs/manage-databases-and-caches/choreo-managed-caches/' - 'monitoring-and-insights/usage-insights.md': 'https://wso2.com/choreo/docs/monitoring-and-insights/insights-overview/' - 'develop-components/configure-mutual-tls-between-components.md': 'https://wso2.com/choreo/docs/authentication-and-authorization/configure-mutual-tls-between-components/' - 'api-management/api-policies.md': 'https://wso2.com/choreo/docs/api-management/api-policies/about-api-policies/' - 'develop-components/develop-services/expose-a-websocket-endpoint-via-a-nodejs-service.md': 'https://wso2.com/choreo/docs/develop-components/develop-services/expose-a-websocket-endpoint-via-a-service/' - 'manage-databases-and-caches/billing-for-platform-services.md': 'https://wso2.com/choreo/docs/references/choreo-platform-services-billing-and-upgrades/' - -extra_css: - # - assets/lib/highlightjs/default.min.css - # - assets/css/theme.css - # - assets/css/prism.css - # - assets/lib/json-formatter/json-formatter.css - - - assets/lib/highlightjs/styles/vs.min.css - - assets/css/blue-palette-alt2.css - - assets/css/choreotheme.css - - assets/lib/json-formatter/json-formatter.css - - assets/css/config-catalog.css - - assets/lib/fontawesome-free-6.3.0-web/css/all.min.css -extra_javascript: - - assets/lib/json-formatter/json-formatter.umd.js - - assets/lib/highlightjs/highlight.min.js - # - assets/js/theme.js - #- assets/js/prism-ballerina.js - - assets/js/choreotheme.js -extra: - social: - - icon: fontawesome/brands/github - link: https://github.com/wso2 -#site_version: 1.0.0 -#base_path: http://localhost:8000 - diff --git a/en/pe-docs/docs/api-management/api-analytics/integrate-choreo-with-moesif.md b/en/pe-docs/docs/api-management/api-analytics/integrate-choreo-with-moesif.md new file mode 100644 index 000000000..1e829136a --- /dev/null +++ b/en/pe-docs/docs/api-management/api-analytics/integrate-choreo-with-moesif.md @@ -0,0 +1,80 @@ +# Integrate Choreo with Moesif + +Moesif is an API analytics and monetization service that helps you grow your API products. You can integrate Choreo with Moesif and gain valuable insights into your API's usage. While Moesif's API analytics capabilities empower you to make informed decision-making on behalf of your organization, its monetization options simplify revenue generation from your APIs, eliminating the need for complex coding. + +In this guide, you will: + +- Generate a key in Moesif. +- Configure Choreo to connect to Moesif. +- Invoke an API and observe the insights on the Moesif dashboard. + +## Step 1: Generate an API key in Moesif + +Let's generate an API key in Moesif. +If you're an existing Moesif user with a registered organization, proceed to [step 1.2](#step-12-access-the-api-key-in-moesif-as-an-existing-user). + +### Step 1.1: Generate a key in Moesif as a new user + +If you are a new user, follow the steps below to register an organization and generate a key: + +1. Go to [https://www.moesif.com/](https://www.moesif.com/). +2. Click **Sign Up** and select an authentication option and proceed. +3. On the **Get Started** page, enter meaningful values for the fields and create a new organization. + + | Field | Description | + |-----------------------|---------------------------------------------------------| + | **Organization Name** | The name of your company or team. | + | **Application Name** | The name of your application that represents one project or environment. | + + 4. Click **Next**. + 5. On the **Overview** page, click **Next**. + + This opens the **Quick Install** page. As there is no data, you cannot proceed. Let's configure Moesif to receive data from Choreo. + + 6. Select a **WSO2 Choreo** as the **Server Integration** + 7. Copy the **Application Id**. + + ![First Time user API Key](../../assets/img/monitoring-and-insights/first_time_key_moesif.png) + + +### Step 1.2: Access the API key in Moesif as an existing user + +If you are an existing user with a registered organization, or you do not have an API key for the organization you created, follow the steps below to access the generated API key: + +1. Go to [https://www.moesif.com/](https://www.moesif.com/). +2. Click on your profile in the bottom left corner, and navigate to the **API Keys** page. +3. Copy the **Collection Application Id**. + + +## Step 2: Integrate Choreo with Moesif + +Let's configure Choreo to publish events to Moesif. + +1. Sign in to [Choreo](https://console.choreo.dev/). +2. In the top navigation menu, click the **Organization** list and select your organization. +3. On the left navigation, click **API Management** and then and click **Moesif Dashboard**. +4. Select the environment you want to publish data for. +5. Paste the **Application Id** you copied. +6. Click **Add**. + +Once you successfully add the key, you will see a delete option next to it. Currently, you can only configure one API key. If you need to add a new API key, you need to delete the existing key and add the new one. + +!!! Note + Once you configure the Moesif API key on Choreo, **wait for five minutes before you publish any data to the Moesif API analytics platform**. + + +## Step 3: Invoke an API and observe the data on the Moesif Dashboard + +1. Invoke your API using a CLI command or a REST client. + + !!! tip + - If you don't have any APIs deployed on Choreo, you can request your developers set up a component or switch to the **Developer View** on the Choreo console and follow the [create and deploy a REST API](https://wso2.com/choreo/docs/develop-components/develop-services/develop-a-rest-api/) guide to get started. + +2. Once you publish data, your Moesif dashboard will receive events. Once Moesif receives events, you will see a notification on Moesif confirming that it received data. + + ![Data Recieved Moesif Notification](../../assets/img/monitoring-and-insights/data_recieved_moesif_notification.png) + +3. Click **Next** on the notification. This will take you to the final step, where you can opt to add team members. In this guide, let's skip this step. +4. Click **Finish**. + +You can now view your API's insights in the Moesif dashboard. diff --git a/en/pe-docs/docs/api-management/consumer-idps/configure-a-user-store-with-built-in-idp.md b/en/pe-docs/docs/api-management/consumer-idps/configure-a-user-store-with-built-in-idp.md new file mode 100644 index 000000000..a42196d44 --- /dev/null +++ b/en/pe-docs/docs/api-management/consumer-idps/configure-a-user-store-with-built-in-idp.md @@ -0,0 +1,33 @@ +# Configure a User Store with the Built-In Identity Provider + +Developers looking to experiment with a complete application development process that includes user authentication and authorization can utilize Choreo's built-in identity provider (IdP). Choreo's built-in identity provider allows you to seamlessly test your application's authentication by setting up test users and groups within Choreo. + +!!! note + Although the built-in IdP facilitates user management support, it is limited to adding users with attributes and groups. Therefore, the built-in IdP user management capabilities are not recommended for use in production. + +## Prerequisites + +Before you try out the steps in this guide, be sure you have administrator rights to your Choreo organization. This permission is essential to configure a user store with the built-in IdP. + +## Configure a Choreo built-in IdP user store + +Follow the steps given below to configure a Choreo built-in IdP user store for an environment: + +1. Go to [https://console.choreo.dev/](https://console.choreo.dev/) and sign in. +2. In the Choreo Console top navigation menu, click the **Organization** list and then click on your organization. +3. In the left navigation menu, click **API Management**. +4. Click the **Consumer IdPs** and then click the **Identity Providers** tab. +5. On the **Identity Providers** tab, click **Manage** in the **Choreo Built-in Identity Provider** pane. +6. In the Manage IdP pane, click on a specific environment tab depending on where you want to configure the built-in IdP user store. +7. You can download the sample **User store template file(.csv )** from the **User Store** section. The template file content is similar to the following: + + ```csv + username,password,groups,first_name,last_name,email + "demouser","password1","[manager, engineering]","John","Doe","john@acme.org" + ``` + +!!! note + The provided template file includes a sample user with associated attributes. To add new users, insert additional rows in the `.csv` file. To include more user attributes, add columns as required in the `.csv` file. + +8. Specify appropriate user details in the template file and save it. +9. Select the template file that you saved and click **Upload**. A successful upload creates the user store and displays the configured users in the **Users** section. diff --git a/en/pe-docs/docs/api-management/consumer-idps/configure-asgardeo-as-an-external-idp.md b/en/pe-docs/docs/api-management/consumer-idps/configure-asgardeo-as-an-external-idp.md new file mode 100644 index 000000000..4111ae48a --- /dev/null +++ b/en/pe-docs/docs/api-management/consumer-idps/configure-asgardeo-as-an-external-idp.md @@ -0,0 +1,39 @@ +# Configure Asgardeo as an External Identity Provider (IdP) + +Asgardeo is an identity-as-a-service (IDaaS) solution designed to create seamless login experiences for your applications. Asgardeo seamlessly integrates with Choreo, providing powerful API access control through the use of API scopes. This enables restricting API access to designated user groups. By configuring Asgardeo as an external IdP in Choreo, you can leverage your Asgardeo user stores to manage API access control effectively. This guide walks you through the steps to set up Asgardeo as your external IdP. + +!!! note + These identity provider settings are for consuming the components deployed within your organization, not for authenticating developers who signing in to the Choreo Console. +## Prerequisites + +Before you proceed, be sure to complete the following: + +- Create an Asgardeo application. You can follow the Asgardeo guide to [register a standard-based application](https://wso2.com/asgardeo/docs/guides/applications/register-standard-based-app/#register-an-application). + +- Find the well-known URL: + Go to the **info** tab of the Asgardeo application to view the endpoints and copy the **Discovery** endpoint. + +- Find the Client ID: + Go to the **Protocol** tab of the Asgardeo application and copy the **Client ID**. + +## Add Asgardeo as an external IdP in Choreo + +Follow the steps below to add Asgardeo as an external IdP in Choreo: + +1. Sign in to the Choreo Console at [https://console.choreo.dev/](https://console.choreo.dev). +2. In the Choreo Console header, go to the **Organization** list and select your organization. +3. In the left navigation menu, click **API Management** and then click on **Consumer IdPs**. +4. Click the **Identity Providers** tab. +5. To add an identity provider, click **+ Identity Provider** +6. Click **Asgardeo**. +7. In the Asgardeo dialog that opens, specify a name and a description for the IdP. +8. In the **Well-Known URL** field, paste the well-known URL that you copied from your Asgardeo instance by following the prerequisites. +9. Leave the **Apply to all environments** checkbox selected. This allows you to use the tokens generated via this IdP to invoke APIs across all environments. + + !!! note + If you want to restrict the use of tokens generated via this IdP to invoke APIs in specific environments, clear the **Apply to all environments** checkbox and select the necessary environments from the **Environments** list. + +10. Click **Next**. This displays the server endpoints that are useful to implement and configure authentication for your application. +11. Click **Add**. + +Now you have configured Asgardeo as an external IdP in Choreo. diff --git a/en/pe-docs/docs/api-management/consumer-idps/configure-azure-ad-as-an-external-idp.md b/en/pe-docs/docs/api-management/consumer-idps/configure-azure-ad-as-an-external-idp.md new file mode 100644 index 000000000..40abda7d5 --- /dev/null +++ b/en/pe-docs/docs/api-management/consumer-idps/configure-azure-ad-as-an-external-idp.md @@ -0,0 +1,35 @@ +# Configure Azure Active Directory (Azure AD) as an External Identity Provider (IdP) + +In organizations leveraging Microsoft Azure Active Directory (Azure AD) for identity and access management (IAM), integrating it with Choreo offers powerful API access control. This control hinges on the use of API scopes. That is, it enables the restriction of access to a designated group of users. This document guide you step-by-step to configure Azure AD as your external IdP. + +!!! note + - You must have **Manage Admin Operations** permission under **APIM-ADMIN** permission group to approve component promotion requests. + - These identity provider settings are used for authentication within components deployed in your organization. They do not apply to authenticating organization members signing into the Choreo Console. + + +## Prerequisites + +Before you try out this guide, be sure you have the following: + +- An Azure Active Directory account: If you don’t already have one, setup an Azure Active Directory account at [https://azure.microsoft.com/en-gb/](https://azure.microsoft.com/en-gb/). + +## Add Azure Active Directory as an external IdP in Choreo + +Follow the steps below to add Azure AD as an IdP in Choreo: + +1. Sign in to the Choreo Console at [https://console.choreo.dev/](https://console.choreo.dev). +2. In the Choreo Console header, go to the **Organization** list and select your organization. +3. In the left navigation menu, click **API Management** and then click on **Consumer IdPs**. +4. Click the **Identity Providers** tab. +5. To add an identity provider, click **+ Identity Provider** +6. Select **Microsoft Entra ID (Azure AD)** as the Identity Provider. +7. Provide a name and a description for the IdP. +8. To obtain the `Well-Known URL` of your Azure AD instance, on your Azure account, under **Azure Active Directory** go to **App registrations**, and then **Endpoints**. Copy the URI under`OpenID Connect metadata document`. + + !!! info + - In azure, there are two versions of access tokens available. By default, the IDP applications you create use the v1 access token. Therefore, if you intend to use the v1 access token, when providing the `Well-Known URL`, omit the v2.0 path segment from the URL. [Learn more](https://learn.microsoft.com/en-us/azure/active-directory/develop/access-tokens#token-formats) + For example, convert `https://login.microsoftonline.com//v2.0/.well-known/openid-configuration`-> `https://login.microsoftonline.com//.well-known/openid-configuration` + - If you intend to work with v2.0, then the IDP application's manifest should be changed as explained in the [access token documentation](https://learn.microsoft.com/en-us/azure/active-directory/develop/access-tokens#token-formats). + +9. Leave the **Apply to all environments** checkbox selected. However, if you want to restrict the use of the external IdP to a certain environment, you can select them from the **Environments** list. +10. Review the endpoints and click **Next**. diff --git a/en/pe-docs/docs/api-management/developer-portal/configure-self-sign-up.md b/en/pe-docs/docs/api-management/developer-portal/configure-self-sign-up.md new file mode 100644 index 000000000..138b8ef0d --- /dev/null +++ b/en/pe-docs/docs/api-management/developer-portal/configure-self-sign-up.md @@ -0,0 +1,135 @@ +# Configure Self-Sign-Up + +With Choreo, you can set up a self-sign-up page for your Developer Portal. The self-sign-up page allows users to easily access your Developer Portal and subscribe to APIs. When you configure self-sign-up, users can create their accounts and access your Developer Portal without any manual intervention from you. + +This page walks you through the steps to configure self-sign-up for your Developer Portal. + +## Prerequisites + +1. Sign in to the Choreo Console at [https://console.choreo.dev/](https://console.choreo.dev/) using your Google, GitHub, or Microsoft account. + +## Configure Developer Portal self-sign-up + +To configure self-sign-up, follow the steps given below: + +1. Send an email to requesting to configure enterprise IdP for the Developer Portal of your organization. + +!!! tip + Ensure you include the organization name or handle in the request. + +!!! note "Sample email" + Subject : [Stark Industries] Configure enterprise IdP for Developer Portal + + Hi CS team, + + I need to configure enterprise IdP for my organization’s Developer Portal to enable self-sign-up. Can you please do the necessary configurations to proceed? + + My organization details are as follows: + + - Organization name: Stark Industries + - Organization handle: starkindustries + + Thank you + + The Choreo support team will perform the necessary configurations and respond to your request. + +2. When you receive a response, sign in to [Asgardeo](https://console.asgardeo.io/) using the same credentials that you used to sign in to Choreo. +3. In the Asgardeo Console, click **View all applications**. + + ![View all applications](../../assets/img/administer/self-sign-up/view-all-applications.png) + + You will see an application named **WSO2_LOGIN_FOR_CHOREO_DEV_PORTAL**. + + ![Applications](../../assets/img/administer/self-sign-up/application.png) + +4. Click on the application to edit it and enter your organization’s Developer Portal URL as the **Access URL** of the application. For example, `https://devportal.choreo.dev/starkindustries`. +5. Click **Update**. +6. To add user attributes, follow these steps: + + !!! info "Note" + If you have enabled enterprise login and you want to add the **Groups** attribute during self-sign-up configuration, avoid making it mandatory. This ensures proper access control and prevents unauthorized privileges. If you make the **Groups** attribute mandatory, it allows self-signed-up users to specify a group and assume roles associated with it. + + 1. Click the **User Attributes** tab. + 2. To add the email as a mandatory user attribute, select **Email** and click the arrow to expand the section. Then, select the **Requested** and **Mandatory** checkboxes. + + ![Email attribute](../../assets/img/administer/self-sign-up/email-attribute.png) + + 3. To add the first name and last name as optional attributes, select **Profile** and click the arrow to expand the section. Then, select the **Requested** checkbox for the **First Name** and the **Last Name** attributes. + + ![Profile attribute](../../assets/img/administer/self-sign-up/profile-attribute.png) + + 4. Click **Update**. + +7. To add the user attributes as OpenID Connect scopes, follow these steps: + + 1. In the Asgardeo Console left navigation menu, click **Scopes**. + 2. In the **OpenID Connect Scopes** pane, click **OpenID** to edit it. + 3. Click **+ New Attribute**. + 4. Select **Email**, **First Name**, and **Last Name** as the attributes to associate with the OpenID scope. + 5. Click **Save** and then click **Save Changes**. + + ![Save attributes as scopes](../../assets/img/administer/self-sign-up/save-attributes-as-scopes.png) + +8. To configure basic authentication as the sign-in method, follow these steps: + + 1. In the Asgardeo Console left navigation menu, click **Applications**. + 2. In the **Applications** pane, click the **WSO2_LOGIN_FOR_CHOREO_DEV_PORTAL** application to edit it. + 3. Click the **Sign-in Method** tab and then click **Start with default configuration**. + + ![Add sign-in method](../../assets/img/administer/self-sign-up/add-sign-in-method.png) + + 4. Click **Update**. + +9. To configure self-registration, follow these steps: + + 1. In the Asgardeo Console left navigation menu, click **Self Registration**. + 2. In the **Self Registration** pane, click **Configure**. + 3. To enable self-registration, turn on the toggle. + 4. Select **Account verification**. This displays a confirmation message to enable account verification. + 5. Click **Continue**. + 6. Specify an appropriate value in the **Account verification link expiry time** field. + 7. Click **Update**. + + ![Configure self-registration](../../assets/img/administer/self-sign-up/configure-self-registration.png) + +Once you complete these steps, you will see a sign up link similar to the following in your Developer Portal: + +![Sign-up](../../assets/img/administer/self-sign-up/sign-up.png){.cInlineImage-half} + +Users can click **LOGIN/SIGN UP** and then click **Create an account** to sign up to access your Developer Portal. + +![Create an account](../../assets/img/administer/self-sign-up/create-an-account.png) + +## Manage new users + +To manage users who want to access your Developer Portal via self-sign-up, you have two possible approaches: + +- Enable auto-approval for new user registrations: This approach automates the user approval process. When you enable auto-approval, each user who creates an account and signs up to your Developer Portal can access it by default. +- Manually approve or reject user accounts: This allows you to review the list of user registrations and manually approve or reject each registration as needed. + +### Enable auto-approval for new user registrations + +To automatically approve each new user account registered on your Developer Portal, follow the steps given below: + +1. Sign in to the Choreo Console at [https://console.choreo.dev/](https://console.choreo.dev). +2. In the Choreo Console header, go to the **Organization** list and select your organization. +3. In the left navigation menu, click **API Management** and then click on **Self Signups**. +4. To enable auto-approval, turn on the toggle. + +Once you enable auto-approval, users can sign in to your Developer Portal and view your APIs and applications immediately after creating an account. + +### Manually approve or reject user accounts + +If you have not enabled auto-approval, you can manually approve or reject new user registrations. Once a user creates an account, Choreo sends an email to ask the user to confirm the account. To manually approve or reject user accounts, follow the steps given below: + +1. Sign in to the Choreo Console at [https://console.choreo.dev/](https://console.choreo.dev). +2. In the Choreo Console header, go to the **Organization** list and select your organization. +3. In the left navigation menu, click **API Management** and then click on **Self Signups**. +4. You will see the user accounts listed for approval. +5. To approve a user account, click **Approve**. To reject an account, click **Reject**. + + - If you approve an account, the user will receive an email confirming the approval. + - If you reject an account, the user will receive an email mentioning that their account is rejected. + +!!! info "Note" + A rejected user cannot sign up to your Developer Portal using the same account again. diff --git a/en/pe-docs/docs/api-management/developer-portal/customize-the-developer-portal.md b/en/pe-docs/docs/api-management/developer-portal/customize-the-developer-portal.md new file mode 100644 index 000000000..e6924c067 --- /dev/null +++ b/en/pe-docs/docs/api-management/developer-portal/customize-the-developer-portal.md @@ -0,0 +1,46 @@ +# Customize the Developer Portal + +The Developer Portal allows API consumers to find and consume APIs with ease. You can change the look and feel of your Developer Portal by changing the theme to match your brand. Doing so will help you give a better developer experience to your users. + +To customize the Developer Portal theme, follow the steps given below: + +!!! Note - + To customize the Developer Portal theme for an organization, you must have **Manage Custom Theme**, **Create Custom Theme**, **View Custom Theme**, **Delete Custom Theme** and/or **Deploy Custom Theme** permission(s) under **ORGANIZATION-MANAGEMENT** permission group respectively. - You cannot undo a change and restore or revert to a previous version of the theme. However, you can reset it to the default theme. + +1. Sign in to the Choreo Console at [https://console.choreo.dev/](https://console.choreo.dev/) using a Google/ GitHub/ Microsoft account. + +2. In the Choreo Console header, go to the **Organization** list and select your organization. + +3. In the left navigation menu, click **API Management** and then click on **Developer Portal**. + +4. Once you access the theme, you can customize the **Home** page, color theme, font, header and footer, logos, etc., by expanding the relevant sections. + +5. Make a change to the theme. For example, let's change the title on the **Home** page and the color theme. + + 1. To update the title on the **Home** page, expand the **Home Page** section, and in the **Title** field, change the default text (for example, to `Try our APIs!`). + + 2. To update the color theme, expand the **Color Palette** section, and change the colors as required (for example, change the background color to `#C3C5CD` and the primary color of the buttons to `#086634`). + + 3. Click **Preview** to view a preview of the Developer Portal with the changes you made. Based on the changes given in the examples, the preview appears as follows. + + ![Preview of customization](../../assets/img/administer/devportal-theme/preview-of-customization.png){.cInlineImage-threeQuarter} + + 4. Click **Save** to save your changes as a draft theme. + + 5. To apply the changes to the Developer Portal, toggle the **Go Live** switch. To confirm that you want to go live with the changes, click **Enable** in the message that appears. + +7. Sign in to the Choreo Developer Portal at [https://devportal.choreo.dev](https://devportal.choreo.dev). + +The **Home** page will appear as it did in the preview. + +## Reset the Developer Portal theme + +To reset the Developer Portal theme to the default theme, follow the steps given below: + +1. Sign in to the Choreo Console at [https://console.choreo.dev/](https://console.choreo.dev/) using a Google, GitHub, or Microsoft account. + +2. In the Choreo Console header, go to the **Organization** list and select your organization. + +3. In the left navigation menu, click **API Management** and then click on **Developer Portal**. + +4. Click **Reset to Default**. diff --git a/en/site/assets/css/blue-palette-alt2.css b/en/pe-docs/docs/assets/css/blue-palette-alt2.css similarity index 100% rename from en/site/assets/css/blue-palette-alt2.css rename to en/pe-docs/docs/assets/css/blue-palette-alt2.css diff --git a/en/site/assets/css/choreotheme.css b/en/pe-docs/docs/assets/css/choreotheme.css similarity index 100% rename from en/site/assets/css/choreotheme.css rename to en/pe-docs/docs/assets/css/choreotheme.css diff --git a/en/site/assets/css/config-catalog.css b/en/pe-docs/docs/assets/css/config-catalog.css similarity index 100% rename from en/site/assets/css/config-catalog.css rename to en/pe-docs/docs/assets/css/config-catalog.css diff --git a/en/site/assets/css/prism.css b/en/pe-docs/docs/assets/css/prism.css similarity index 100% rename from en/site/assets/css/prism.css rename to en/pe-docs/docs/assets/css/prism.css diff --git a/en/site/assets/css/style.css b/en/pe-docs/docs/assets/css/style.css old mode 100644 new mode 100755 similarity index 100% rename from en/site/assets/css/style.css rename to en/pe-docs/docs/assets/css/style.css diff --git a/en/site/assets/css/theme.css b/en/pe-docs/docs/assets/css/theme.css similarity index 100% rename from en/site/assets/css/theme.css rename to en/pe-docs/docs/assets/css/theme.css diff --git a/en/site/assets/img/administer/access-control-to-console.png b/en/pe-docs/docs/assets/img/administer/access-control-to-console.png similarity index 100% rename from en/site/assets/img/administer/access-control-to-console.png rename to en/pe-docs/docs/assets/img/administer/access-control-to-console.png diff --git a/en/pe-docs/docs/assets/img/administer/add-project-level-rules.png b/en/pe-docs/docs/assets/img/administer/add-project-level-rules.png new file mode 100644 index 000000000..55856f5d2 Binary files /dev/null and b/en/pe-docs/docs/assets/img/administer/add-project-level-rules.png differ diff --git a/en/site/assets/img/administer/api-with-custom-url.png b/en/pe-docs/docs/assets/img/administer/api-with-custom-url.png similarity index 100% rename from en/site/assets/img/administer/api-with-custom-url.png rename to en/pe-docs/docs/assets/img/administer/api-with-custom-url.png diff --git a/en/pe-docs/docs/assets/img/administer/configure-an-organization-level-egress-policy.png b/en/pe-docs/docs/assets/img/administer/configure-an-organization-level-egress-policy.png new file mode 100644 index 000000000..d03f34838 Binary files /dev/null and b/en/pe-docs/docs/assets/img/administer/configure-an-organization-level-egress-policy.png differ diff --git a/en/site/assets/img/administer/configure-domain/active-deployments.png b/en/pe-docs/docs/assets/img/administer/configure-domain/active-deployments.png similarity index 100% rename from en/site/assets/img/administer/configure-domain/active-deployments.png rename to en/pe-docs/docs/assets/img/administer/configure-domain/active-deployments.png diff --git a/en/pe-docs/docs/assets/img/administer/configure-domain/active-domains.png b/en/pe-docs/docs/assets/img/administer/configure-domain/active-domains.png new file mode 100644 index 000000000..b55522cfb Binary files /dev/null and b/en/pe-docs/docs/assets/img/administer/configure-domain/active-domains.png differ diff --git a/en/site/assets/img/administer/configure-domain/cname-target-value.png b/en/pe-docs/docs/assets/img/administer/configure-domain/cname-target-value.png similarity index 100% rename from en/site/assets/img/administer/configure-domain/cname-target-value.png rename to en/pe-docs/docs/assets/img/administer/configure-domain/cname-target-value.png diff --git a/en/pe-docs/docs/assets/img/administer/configure-domain/custom-url.png b/en/pe-docs/docs/assets/img/administer/configure-domain/custom-url.png new file mode 100644 index 000000000..602fe4616 Binary files /dev/null and b/en/pe-docs/docs/assets/img/administer/configure-domain/custom-url.png differ diff --git a/en/site/assets/img/administer/configure-domain/developer-portal-cname-target-value.png b/en/pe-docs/docs/assets/img/administer/configure-domain/developer-portal-cname-target-value.png similarity index 100% rename from en/site/assets/img/administer/configure-domain/developer-portal-cname-target-value.png rename to en/pe-docs/docs/assets/img/administer/configure-domain/developer-portal-cname-target-value.png diff --git a/en/site/assets/img/administer/configure-domain/pending-custom-url-request.png b/en/pe-docs/docs/assets/img/administer/configure-domain/pending-custom-url-request.png similarity index 100% rename from en/site/assets/img/administer/configure-domain/pending-custom-url-request.png rename to en/pe-docs/docs/assets/img/administer/configure-domain/pending-custom-url-request.png diff --git a/en/pe-docs/docs/assets/img/administer/configure-domain/pending-url-requests.png b/en/pe-docs/docs/assets/img/administer/configure-domain/pending-url-requests.png new file mode 100644 index 000000000..32d323655 Binary files /dev/null and b/en/pe-docs/docs/assets/img/administer/configure-domain/pending-url-requests.png differ diff --git a/en/pe-docs/docs/assets/img/administer/configure-domain/upload-certificate-chain.png b/en/pe-docs/docs/assets/img/administer/configure-domain/upload-certificate-chain.png new file mode 100644 index 000000000..908520284 Binary files /dev/null and b/en/pe-docs/docs/assets/img/administer/configure-domain/upload-certificate-chain.png differ diff --git a/en/site/assets/img/administer/configure-domain/url-settings.png b/en/pe-docs/docs/assets/img/administer/configure-domain/url-settings.png similarity index 100% rename from en/site/assets/img/administer/configure-domain/url-settings.png rename to en/pe-docs/docs/assets/img/administer/configure-domain/url-settings.png diff --git a/en/site/assets/img/administer/create-choreo-organization.png b/en/pe-docs/docs/assets/img/administer/create-choreo-organization.png similarity index 100% rename from en/site/assets/img/administer/create-choreo-organization.png rename to en/pe-docs/docs/assets/img/administer/create-choreo-organization.png diff --git a/en/site/assets/img/administer/create-custom-domain.png b/en/pe-docs/docs/assets/img/administer/create-custom-domain.png similarity index 100% rename from en/site/assets/img/administer/create-custom-domain.png rename to en/pe-docs/docs/assets/img/administer/create-custom-domain.png diff --git a/en/pe-docs/docs/assets/img/administer/create-subscription-plan.png b/en/pe-docs/docs/assets/img/administer/create-subscription-plan.png new file mode 100644 index 000000000..f6189d028 Binary files /dev/null and b/en/pe-docs/docs/assets/img/administer/create-subscription-plan.png differ diff --git a/en/site/assets/img/administer/devportal-theme/access-devportal-theme.png b/en/pe-docs/docs/assets/img/administer/devportal-theme/access-devportal-theme.png similarity index 100% rename from en/site/assets/img/administer/devportal-theme/access-devportal-theme.png rename to en/pe-docs/docs/assets/img/administer/devportal-theme/access-devportal-theme.png diff --git a/en/site/assets/img/administer/devportal-theme/preview-of-customization.png b/en/pe-docs/docs/assets/img/administer/devportal-theme/preview-of-customization.png similarity index 100% rename from en/site/assets/img/administer/devportal-theme/preview-of-customization.png rename to en/pe-docs/docs/assets/img/administer/devportal-theme/preview-of-customization.png diff --git a/en/site/assets/img/administer/devportal-theme/publish-or-discard-developer-portal-changes.png b/en/pe-docs/docs/assets/img/administer/devportal-theme/publish-or-discard-developer-portal-changes.png similarity index 100% rename from en/site/assets/img/administer/devportal-theme/publish-or-discard-developer-portal-changes.png rename to en/pe-docs/docs/assets/img/administer/devportal-theme/publish-or-discard-developer-portal-changes.png diff --git a/en/pe-docs/docs/assets/img/administer/enterprise-login/group-mapping.png b/en/pe-docs/docs/assets/img/administer/enterprise-login/group-mapping.png new file mode 100644 index 000000000..7f3f81405 Binary files /dev/null and b/en/pe-docs/docs/assets/img/administer/enterprise-login/group-mapping.png differ diff --git a/en/site/assets/img/administer/enterprise-login/role-mapping.png b/en/pe-docs/docs/assets/img/administer/enterprise-login/role-mapping.png similarity index 100% rename from en/site/assets/img/administer/enterprise-login/role-mapping.png rename to en/pe-docs/docs/assets/img/administer/enterprise-login/role-mapping.png diff --git a/en/site/assets/img/administer/list-custom-domain.png b/en/pe-docs/docs/assets/img/administer/list-custom-domain.png similarity index 100% rename from en/site/assets/img/administer/list-custom-domain.png rename to en/pe-docs/docs/assets/img/administer/list-custom-domain.png diff --git a/en/site/assets/img/administer/mapping-level.png b/en/pe-docs/docs/assets/img/administer/mapping-level.png similarity index 100% rename from en/site/assets/img/administer/mapping-level.png rename to en/pe-docs/docs/assets/img/administer/mapping-level.png diff --git a/en/site/assets/img/administer/organizations.png b/en/pe-docs/docs/assets/img/administer/organizations.png similarity index 100% rename from en/site/assets/img/administer/organizations.png rename to en/pe-docs/docs/assets/img/administer/organizations.png diff --git a/en/site/assets/img/administer/self-sign-up/add-sign-in-method.png b/en/pe-docs/docs/assets/img/administer/self-sign-up/add-sign-in-method.png similarity index 100% rename from en/site/assets/img/administer/self-sign-up/add-sign-in-method.png rename to en/pe-docs/docs/assets/img/administer/self-sign-up/add-sign-in-method.png diff --git a/en/site/assets/img/administer/self-sign-up/application.png b/en/pe-docs/docs/assets/img/administer/self-sign-up/application.png similarity index 100% rename from en/site/assets/img/administer/self-sign-up/application.png rename to en/pe-docs/docs/assets/img/administer/self-sign-up/application.png diff --git a/en/site/assets/img/administer/self-sign-up/approval-pending.png b/en/pe-docs/docs/assets/img/administer/self-sign-up/approval-pending.png similarity index 100% rename from en/site/assets/img/administer/self-sign-up/approval-pending.png rename to en/pe-docs/docs/assets/img/administer/self-sign-up/approval-pending.png diff --git a/en/site/assets/img/administer/self-sign-up/configure-self-registration.png b/en/pe-docs/docs/assets/img/administer/self-sign-up/configure-self-registration.png similarity index 100% rename from en/site/assets/img/administer/self-sign-up/configure-self-registration.png rename to en/pe-docs/docs/assets/img/administer/self-sign-up/configure-self-registration.png diff --git a/en/site/assets/img/administer/self-sign-up/copy-handle.png b/en/pe-docs/docs/assets/img/administer/self-sign-up/copy-handle.png similarity index 100% rename from en/site/assets/img/administer/self-sign-up/copy-handle.png rename to en/pe-docs/docs/assets/img/administer/self-sign-up/copy-handle.png diff --git a/en/site/assets/img/administer/self-sign-up/create-an-account.png b/en/pe-docs/docs/assets/img/administer/self-sign-up/create-an-account.png similarity index 100% rename from en/site/assets/img/administer/self-sign-up/create-an-account.png rename to en/pe-docs/docs/assets/img/administer/self-sign-up/create-an-account.png diff --git a/en/site/assets/img/administer/self-sign-up/create-new-organization.png b/en/pe-docs/docs/assets/img/administer/self-sign-up/create-new-organization.png similarity index 100% rename from en/site/assets/img/administer/self-sign-up/create-new-organization.png rename to en/pe-docs/docs/assets/img/administer/self-sign-up/create-new-organization.png diff --git a/en/site/assets/img/administer/self-sign-up/create-organization.png b/en/pe-docs/docs/assets/img/administer/self-sign-up/create-organization.png similarity index 100% rename from en/site/assets/img/administer/self-sign-up/create-organization.png rename to en/pe-docs/docs/assets/img/administer/self-sign-up/create-organization.png diff --git a/en/site/assets/img/administer/self-sign-up/email-attribute.png b/en/pe-docs/docs/assets/img/administer/self-sign-up/email-attribute.png similarity index 100% rename from en/site/assets/img/administer/self-sign-up/email-attribute.png rename to en/pe-docs/docs/assets/img/administer/self-sign-up/email-attribute.png diff --git a/en/site/assets/img/administer/self-sign-up/profile-attribute.png b/en/pe-docs/docs/assets/img/administer/self-sign-up/profile-attribute.png similarity index 100% rename from en/site/assets/img/administer/self-sign-up/profile-attribute.png rename to en/pe-docs/docs/assets/img/administer/self-sign-up/profile-attribute.png diff --git a/en/site/assets/img/administer/self-sign-up/save-attributes-as-scopes.png b/en/pe-docs/docs/assets/img/administer/self-sign-up/save-attributes-as-scopes.png similarity index 100% rename from en/site/assets/img/administer/self-sign-up/save-attributes-as-scopes.png rename to en/pe-docs/docs/assets/img/administer/self-sign-up/save-attributes-as-scopes.png diff --git a/en/site/assets/img/administer/self-sign-up/sign-up.png b/en/pe-docs/docs/assets/img/administer/self-sign-up/sign-up.png similarity index 100% rename from en/site/assets/img/administer/self-sign-up/sign-up.png rename to en/pe-docs/docs/assets/img/administer/self-sign-up/sign-up.png diff --git a/en/site/assets/img/administer/self-sign-up/user-attributes.png b/en/pe-docs/docs/assets/img/administer/self-sign-up/user-attributes.png similarity index 100% rename from en/site/assets/img/administer/self-sign-up/user-attributes.png rename to en/pe-docs/docs/assets/img/administer/self-sign-up/user-attributes.png diff --git a/en/site/assets/img/administer/self-sign-up/view-all-applications.png b/en/pe-docs/docs/assets/img/administer/self-sign-up/view-all-applications.png similarity index 100% rename from en/site/assets/img/administer/self-sign-up/view-all-applications.png rename to en/pe-docs/docs/assets/img/administer/self-sign-up/view-all-applications.png diff --git a/en/site/assets/img/api-management/api-discovery.png b/en/pe-docs/docs/assets/img/api-management/api-discovery.png similarity index 100% rename from en/site/assets/img/api-management/api-discovery.png rename to en/pe-docs/docs/assets/img/api-management/api-discovery.png diff --git a/en/site/assets/img/api-management/api-policies/add-header.png b/en/pe-docs/docs/assets/img/api-management/api-policies/add-header.png similarity index 100% rename from en/site/assets/img/api-management/api-policies/add-header.png rename to en/pe-docs/docs/assets/img/api-management/api-policies/add-header.png diff --git a/en/site/assets/img/api-management/api-policies/add-policy.png b/en/pe-docs/docs/assets/img/api-management/api-policies/add-policy.png similarity index 100% rename from en/site/assets/img/api-management/api-policies/add-policy.png rename to en/pe-docs/docs/assets/img/api-management/api-policies/add-policy.png diff --git a/en/site/assets/img/api-management/api-policies/added-policy.png b/en/pe-docs/docs/assets/img/api-management/api-policies/added-policy.png similarity index 100% rename from en/site/assets/img/api-management/api-policies/added-policy.png rename to en/pe-docs/docs/assets/img/api-management/api-policies/added-policy.png diff --git a/en/pe-docs/docs/assets/img/api-management/api-policies/advanced-settings/detailed-access-log-setting.png b/en/pe-docs/docs/assets/img/api-management/api-policies/advanced-settings/detailed-access-log-setting.png new file mode 100644 index 000000000..356209025 Binary files /dev/null and b/en/pe-docs/docs/assets/img/api-management/api-policies/advanced-settings/detailed-access-log-setting.png differ diff --git a/en/pe-docs/docs/assets/img/api-management/api-policies/advanced-settings/hostname-verification-setting.png b/en/pe-docs/docs/assets/img/api-management/api-policies/advanced-settings/hostname-verification-setting.png new file mode 100644 index 000000000..f9336ba0b Binary files /dev/null and b/en/pe-docs/docs/assets/img/api-management/api-policies/advanced-settings/hostname-verification-setting.png differ diff --git a/en/pe-docs/docs/assets/img/api-management/api-policies/advanced-settings/http-version-setting.png b/en/pe-docs/docs/assets/img/api-management/api-policies/advanced-settings/http-version-setting.png new file mode 100644 index 000000000..4c1d948b7 Binary files /dev/null and b/en/pe-docs/docs/assets/img/api-management/api-policies/advanced-settings/http-version-setting.png differ diff --git a/en/pe-docs/docs/assets/img/api-management/api-policies/advanced-settings/minimum-evictable-idle-time-setting.png b/en/pe-docs/docs/assets/img/api-management/api-policies/advanced-settings/minimum-evictable-idle-time-setting.png new file mode 100644 index 000000000..9ad89c969 Binary files /dev/null and b/en/pe-docs/docs/assets/img/api-management/api-policies/advanced-settings/minimum-evictable-idle-time-setting.png differ diff --git a/en/site/assets/img/api-management/api-policies/attach-policy.png b/en/pe-docs/docs/assets/img/api-management/api-policies/attach-policy.png similarity index 100% rename from en/site/assets/img/api-management/api-policies/attach-policy.png rename to en/pe-docs/docs/assets/img/api-management/api-policies/attach-policy.png diff --git a/en/site/assets/img/api-management/api-policies/ballerina-project.png b/en/pe-docs/docs/assets/img/api-management/api-policies/ballerina-project.png similarity index 100% rename from en/site/assets/img/api-management/api-policies/ballerina-project.png rename to en/pe-docs/docs/assets/img/api-management/api-policies/ballerina-project.png diff --git a/en/site/assets/img/api-management/api-policies/ballerina-toml.png b/en/pe-docs/docs/assets/img/api-management/api-policies/ballerina-toml.png similarity index 100% rename from en/site/assets/img/api-management/api-policies/ballerina-toml.png rename to en/pe-docs/docs/assets/img/api-management/api-policies/ballerina-toml.png diff --git a/en/site/assets/img/api-management/api-policies/configurable-values.png b/en/pe-docs/docs/assets/img/api-management/api-policies/configurable-values.png similarity index 100% rename from en/site/assets/img/api-management/api-policies/configurable-values.png rename to en/pe-docs/docs/assets/img/api-management/api-policies/configurable-values.png diff --git a/en/site/assets/img/api-management/api-policies/configure-add-header.png b/en/pe-docs/docs/assets/img/api-management/api-policies/configure-add-header.png similarity index 100% rename from en/site/assets/img/api-management/api-policies/configure-add-header.png rename to en/pe-docs/docs/assets/img/api-management/api-policies/configure-add-header.png diff --git a/en/site/assets/img/api-management/api-policies/configure-parameters.png b/en/pe-docs/docs/assets/img/api-management/api-policies/configure-parameters.png similarity index 100% rename from en/site/assets/img/api-management/api-policies/configure-parameters.png rename to en/pe-docs/docs/assets/img/api-management/api-policies/configure-parameters.png diff --git a/en/site/assets/img/api-management/api-policies/published-policy.png b/en/pe-docs/docs/assets/img/api-management/api-policies/published-policy.png similarity index 100% rename from en/site/assets/img/api-management/api-policies/published-policy.png rename to en/pe-docs/docs/assets/img/api-management/api-policies/published-policy.png diff --git a/en/site/assets/img/api-management/api-policies/request-response-flow.png b/en/pe-docs/docs/assets/img/api-management/api-policies/request-response-flow.png similarity index 100% rename from en/site/assets/img/api-management/api-policies/request-response-flow.png rename to en/pe-docs/docs/assets/img/api-management/api-policies/request-response-flow.png diff --git a/en/site/assets/img/api-management/api-policies/save-and-deploy.png b/en/pe-docs/docs/assets/img/api-management/api-policies/save-and-deploy.png similarity index 100% rename from en/site/assets/img/api-management/api-policies/save-and-deploy.png rename to en/pe-docs/docs/assets/img/api-management/api-policies/save-and-deploy.png diff --git a/en/site/assets/img/api-management/api-policies/select-policy.png b/en/pe-docs/docs/assets/img/api-management/api-policies/select-policy.png similarity index 100% rename from en/site/assets/img/api-management/api-policies/select-policy.png rename to en/pe-docs/docs/assets/img/api-management/api-policies/select-policy.png diff --git a/en/site/assets/img/api-management/applications.png b/en/pe-docs/docs/assets/img/api-management/applications.png similarity index 100% rename from en/site/assets/img/api-management/applications.png rename to en/pe-docs/docs/assets/img/api-management/applications.png diff --git a/en/site/assets/img/api-management/authentication.png b/en/pe-docs/docs/assets/img/api-management/authentication.png similarity index 100% rename from en/site/assets/img/api-management/authentication.png rename to en/pe-docs/docs/assets/img/api-management/authentication.png diff --git a/en/site/assets/img/api-management/business-plans.png b/en/pe-docs/docs/assets/img/api-management/business-plans.png similarity index 100% rename from en/site/assets/img/api-management/business-plans.png rename to en/pe-docs/docs/assets/img/api-management/business-plans.png diff --git a/en/site/assets/img/api-management/developer-portal-home-page.png b/en/pe-docs/docs/assets/img/api-management/developer-portal-home-page.png similarity index 100% rename from en/site/assets/img/api-management/developer-portal-home-page.png rename to en/pe-docs/docs/assets/img/api-management/developer-portal-home-page.png diff --git a/en/site/assets/img/api-management/invoke-api.png b/en/pe-docs/docs/assets/img/api-management/invoke-api.png similarity index 100% rename from en/site/assets/img/api-management/invoke-api.png rename to en/pe-docs/docs/assets/img/api-management/invoke-api.png diff --git a/en/site/assets/img/api-management/manage-api-traffic/add-subscription.png b/en/pe-docs/docs/assets/img/api-management/manage-api-traffic/add-subscription.png similarity index 53% rename from en/site/assets/img/api-management/manage-api-traffic/add-subscription.png rename to en/pe-docs/docs/assets/img/api-management/manage-api-traffic/add-subscription.png index a6e5e84d3..d5a159f97 100644 Binary files a/en/site/assets/img/api-management/manage-api-traffic/add-subscription.png and b/en/pe-docs/docs/assets/img/api-management/manage-api-traffic/add-subscription.png differ diff --git a/en/pe-docs/docs/assets/img/api-management/manage-api-traffic/enable-toggle.png b/en/pe-docs/docs/assets/img/api-management/manage-api-traffic/enable-toggle.png new file mode 100644 index 000000000..61566d667 Binary files /dev/null and b/en/pe-docs/docs/assets/img/api-management/manage-api-traffic/enable-toggle.png differ diff --git a/en/site/assets/img/api-management/manage-api-traffic/throttle-response.png b/en/pe-docs/docs/assets/img/api-management/manage-api-traffic/throttle-response.png similarity index 100% rename from en/site/assets/img/api-management/manage-api-traffic/throttle-response.png rename to en/pe-docs/docs/assets/img/api-management/manage-api-traffic/throttle-response.png diff --git a/en/site/assets/img/api-management/subscription.png b/en/pe-docs/docs/assets/img/api-management/subscription.png similarity index 100% rename from en/site/assets/img/api-management/subscription.png rename to en/pe-docs/docs/assets/img/api-management/subscription.png diff --git a/en/site/assets/img/authentication-and-authorization/associate-certificate.png b/en/pe-docs/docs/assets/img/authentication-and-authorization/associate-certificate.png similarity index 100% rename from en/site/assets/img/authentication-and-authorization/associate-certificate.png rename to en/pe-docs/docs/assets/img/authentication-and-authorization/associate-certificate.png diff --git a/en/site/assets/img/authentication-and-authorization/certificate-details.png b/en/pe-docs/docs/assets/img/authentication-and-authorization/certificate-details.png similarity index 100% rename from en/site/assets/img/authentication-and-authorization/certificate-details.png rename to en/pe-docs/docs/assets/img/authentication-and-authorization/certificate-details.png diff --git a/en/site/assets/img/authentication-and-authorization/generate-new-key-pair.png b/en/pe-docs/docs/assets/img/authentication-and-authorization/generate-new-key-pair.png similarity index 100% rename from en/site/assets/img/authentication-and-authorization/generate-new-key-pair.png rename to en/pe-docs/docs/assets/img/authentication-and-authorization/generate-new-key-pair.png diff --git a/en/site/assets/img/authentication-and-authorization/mutual-ssl-authentication.png b/en/pe-docs/docs/assets/img/authentication-and-authorization/mutual-ssl-authentication.png similarity index 100% rename from en/site/assets/img/authentication-and-authorization/mutual-ssl-authentication.png rename to en/pe-docs/docs/assets/img/authentication-and-authorization/mutual-ssl-authentication.png diff --git a/en/site/assets/img/authentication-and-authorization/use-own-key-pair.png b/en/pe-docs/docs/assets/img/authentication-and-authorization/use-own-key-pair.png similarity index 100% rename from en/site/assets/img/authentication-and-authorization/use-own-key-pair.png rename to en/pe-docs/docs/assets/img/authentication-and-authorization/use-own-key-pair.png diff --git a/en/site/assets/img/authentication-and-authorization/view-and-download.png b/en/pe-docs/docs/assets/img/authentication-and-authorization/view-and-download.png similarity index 100% rename from en/site/assets/img/authentication-and-authorization/view-and-download.png rename to en/pe-docs/docs/assets/img/authentication-and-authorization/view-and-download.png diff --git a/en/pe-docs/docs/assets/img/choreo-cli/personal-access-tokens/account-settings.png b/en/pe-docs/docs/assets/img/choreo-cli/personal-access-tokens/account-settings.png new file mode 100644 index 000000000..01a21b9f0 Binary files /dev/null and b/en/pe-docs/docs/assets/img/choreo-cli/personal-access-tokens/account-settings.png differ diff --git a/en/pe-docs/docs/assets/img/choreo-cli/personal-access-tokens/create-a-pat.png b/en/pe-docs/docs/assets/img/choreo-cli/personal-access-tokens/create-a-pat.png new file mode 100644 index 000000000..80b975d6b Binary files /dev/null and b/en/pe-docs/docs/assets/img/choreo-cli/personal-access-tokens/create-a-pat.png differ diff --git a/en/pe-docs/docs/assets/img/choreo-cli/personal-access-tokens/generated-pat.png b/en/pe-docs/docs/assets/img/choreo-cli/personal-access-tokens/generated-pat.png new file mode 100644 index 000000000..bf5a919b3 Binary files /dev/null and b/en/pe-docs/docs/assets/img/choreo-cli/personal-access-tokens/generated-pat.png differ diff --git a/en/pe-docs/docs/assets/img/choreo-cli/personal-access-tokens/pat-listing.png b/en/pe-docs/docs/assets/img/choreo-cli/personal-access-tokens/pat-listing.png new file mode 100644 index 000000000..e92ffee00 Binary files /dev/null and b/en/pe-docs/docs/assets/img/choreo-cli/personal-access-tokens/pat-listing.png differ diff --git a/en/pe-docs/docs/assets/img/choreo-cli/personal-access-tokens/profile.png b/en/pe-docs/docs/assets/img/choreo-cli/personal-access-tokens/profile.png new file mode 100644 index 000000000..c0f54c24d Binary files /dev/null and b/en/pe-docs/docs/assets/img/choreo-cli/personal-access-tokens/profile.png differ diff --git a/en/site/assets/img/choreo-concepts/choreo-environments.png b/en/pe-docs/docs/assets/img/choreo-concepts/choreo-environments.png similarity index 100% rename from en/site/assets/img/choreo-concepts/choreo-environments.png rename to en/pe-docs/docs/assets/img/choreo-concepts/choreo-environments.png diff --git a/en/site/assets/img/choreo-concepts/deployment-tracks-api-versioning.md.png b/en/pe-docs/docs/assets/img/choreo-concepts/deployment-tracks-api-versioning.md.png similarity index 100% rename from en/site/assets/img/choreo-concepts/deployment-tracks-api-versioning.md.png rename to en/pe-docs/docs/assets/img/choreo-concepts/deployment-tracks-api-versioning.md.png diff --git a/en/site/assets/img/choreo-concepts/deployment-tracks-container-registry.png b/en/pe-docs/docs/assets/img/choreo-concepts/deployment-tracks-container-registry.png similarity index 100% rename from en/site/assets/img/choreo-concepts/deployment-tracks-container-registry.png rename to en/pe-docs/docs/assets/img/choreo-concepts/deployment-tracks-container-registry.png diff --git a/en/site/assets/img/choreo-concepts/deployment-tracks-source-repo.png b/en/pe-docs/docs/assets/img/choreo-concepts/deployment-tracks-source-repo.png similarity index 100% rename from en/site/assets/img/choreo-concepts/deployment-tracks-source-repo.png rename to en/pe-docs/docs/assets/img/choreo-concepts/deployment-tracks-source-repo.png diff --git a/en/site/assets/img/choreo-concepts/environments-and-dataplanes.png b/en/pe-docs/docs/assets/img/choreo-concepts/environments-and-dataplanes.png similarity index 100% rename from en/site/assets/img/choreo-concepts/environments-and-dataplanes.png rename to en/pe-docs/docs/assets/img/choreo-concepts/environments-and-dataplanes.png diff --git a/en/site/assets/img/choreo-concepts/high-level-view.png b/en/pe-docs/docs/assets/img/choreo-concepts/high-level-view.png similarity index 100% rename from en/site/assets/img/choreo-concepts/high-level-view.png rename to en/pe-docs/docs/assets/img/choreo-concepts/high-level-view.png diff --git a/en/site/assets/img/choreo-concepts/marketplace/internal-marketplace.png b/en/pe-docs/docs/assets/img/choreo-concepts/marketplace/internal-marketplace.png similarity index 100% rename from en/site/assets/img/choreo-concepts/marketplace/internal-marketplace.png rename to en/pe-docs/docs/assets/img/choreo-concepts/marketplace/internal-marketplace.png diff --git a/en/site/assets/img/choreo-concepts/observability-architecture.png b/en/pe-docs/docs/assets/img/choreo-concepts/observability-architecture.png similarity index 100% rename from en/site/assets/img/choreo-concepts/observability-architecture.png rename to en/pe-docs/docs/assets/img/choreo-concepts/observability-architecture.png diff --git a/en/site/assets/img/choreo-concepts/private-data-plane-architecture.png b/en/pe-docs/docs/assets/img/choreo-concepts/private-data-plane-architecture.png similarity index 100% rename from en/site/assets/img/choreo-concepts/private-data-plane-architecture.png rename to en/pe-docs/docs/assets/img/choreo-concepts/private-data-plane-architecture.png diff --git a/en/site/assets/img/choreo-concepts/project.png b/en/pe-docs/docs/assets/img/choreo-concepts/project.png similarity index 100% rename from en/site/assets/img/choreo-concepts/project.png rename to en/pe-docs/docs/assets/img/choreo-concepts/project.png diff --git a/en/site/assets/img/choreo-concepts/resource-hierarchy.png b/en/pe-docs/docs/assets/img/choreo-concepts/resource-hierarchy.png similarity index 100% rename from en/site/assets/img/choreo-concepts/resource-hierarchy.png rename to en/pe-docs/docs/assets/img/choreo-concepts/resource-hierarchy.png diff --git a/en/site/assets/img/choreo-concepts/saas-data-plane-architecture.png b/en/pe-docs/docs/assets/img/choreo-concepts/saas-data-plane-architecture.png similarity index 100% rename from en/site/assets/img/choreo-concepts/saas-data-plane-architecture.png rename to en/pe-docs/docs/assets/img/choreo-concepts/saas-data-plane-architecture.png diff --git a/en/site/assets/img/choreo-logo.png b/en/pe-docs/docs/assets/img/choreo-logo.png similarity index 100% rename from en/site/assets/img/choreo-logo.png rename to en/pe-docs/docs/assets/img/choreo-logo.png diff --git a/en/site/assets/img/consume/add-apis.png b/en/pe-docs/docs/assets/img/consume/add-apis.png similarity index 100% rename from en/site/assets/img/consume/add-apis.png rename to en/pe-docs/docs/assets/img/consume/add-apis.png diff --git a/en/site/assets/img/consume/api-overview.png b/en/pe-docs/docs/assets/img/consume/api-overview.png similarity index 100% rename from en/site/assets/img/consume/api-overview.png rename to en/pe-docs/docs/assets/img/consume/api-overview.png diff --git a/en/site/assets/img/consume/developer-portal-apis.png b/en/pe-docs/docs/assets/img/consume/developer-portal-apis.png similarity index 100% rename from en/site/assets/img/consume/developer-portal-apis.png rename to en/pe-docs/docs/assets/img/consume/developer-portal-apis.png diff --git a/en/pe-docs/docs/assets/img/cost-optimization/ComponentLevel.png b/en/pe-docs/docs/assets/img/cost-optimization/ComponentLevel.png new file mode 100644 index 000000000..029a67f9f Binary files /dev/null and b/en/pe-docs/docs/assets/img/cost-optimization/ComponentLevel.png differ diff --git a/en/pe-docs/docs/assets/img/cost-optimization/OrganizationLevel.png b/en/pe-docs/docs/assets/img/cost-optimization/OrganizationLevel.png new file mode 100644 index 000000000..620550040 Binary files /dev/null and b/en/pe-docs/docs/assets/img/cost-optimization/OrganizationLevel.png differ diff --git a/en/pe-docs/docs/assets/img/cost-optimization/ProjectLevel.png b/en/pe-docs/docs/assets/img/cost-optimization/ProjectLevel.png new file mode 100644 index 000000000..4930de1dd Binary files /dev/null and b/en/pe-docs/docs/assets/img/cost-optimization/ProjectLevel.png differ diff --git a/en/pe-docs/docs/assets/img/cost-optimization/annual_savings.png b/en/pe-docs/docs/assets/img/cost-optimization/annual_savings.png new file mode 100644 index 000000000..0316fd150 Binary files /dev/null and b/en/pe-docs/docs/assets/img/cost-optimization/annual_savings.png differ diff --git a/en/pe-docs/docs/assets/img/cost-optimization/component_details.png b/en/pe-docs/docs/assets/img/cost-optimization/component_details.png new file mode 100644 index 000000000..107be7bf4 Binary files /dev/null and b/en/pe-docs/docs/assets/img/cost-optimization/component_details.png differ diff --git a/en/pe-docs/docs/assets/img/cost-optimization/component_metrics_cards.png b/en/pe-docs/docs/assets/img/cost-optimization/component_metrics_cards.png new file mode 100644 index 000000000..74401bbe8 Binary files /dev/null and b/en/pe-docs/docs/assets/img/cost-optimization/component_metrics_cards.png differ diff --git a/en/pe-docs/docs/assets/img/cost-optimization/component_summary.png b/en/pe-docs/docs/assets/img/cost-optimization/component_summary.png new file mode 100644 index 000000000..4bf959dc1 Binary files /dev/null and b/en/pe-docs/docs/assets/img/cost-optimization/component_summary.png differ diff --git a/en/pe-docs/docs/assets/img/cost-optimization/cost_analysis.png b/en/pe-docs/docs/assets/img/cost-optimization/cost_analysis.png new file mode 100644 index 000000000..d86cc6357 Binary files /dev/null and b/en/pe-docs/docs/assets/img/cost-optimization/cost_analysis.png differ diff --git a/en/pe-docs/docs/assets/img/cost-optimization/cpu_metrics.png b/en/pe-docs/docs/assets/img/cost-optimization/cpu_metrics.png new file mode 100644 index 000000000..bb0bfc6f8 Binary files /dev/null and b/en/pe-docs/docs/assets/img/cost-optimization/cpu_metrics.png differ diff --git a/en/pe-docs/docs/assets/img/cost-optimization/deployment_summary.png b/en/pe-docs/docs/assets/img/cost-optimization/deployment_summary.png new file mode 100644 index 000000000..08f2a564a Binary files /dev/null and b/en/pe-docs/docs/assets/img/cost-optimization/deployment_summary.png differ diff --git a/en/pe-docs/docs/assets/img/cost-optimization/estimated_monthly_cost.png b/en/pe-docs/docs/assets/img/cost-optimization/estimated_monthly_cost.png new file mode 100644 index 000000000..ab5a5cd5b Binary files /dev/null and b/en/pe-docs/docs/assets/img/cost-optimization/estimated_monthly_cost.png differ diff --git a/en/pe-docs/docs/assets/img/cost-optimization/memory_metrics.png b/en/pe-docs/docs/assets/img/cost-optimization/memory_metrics.png new file mode 100644 index 000000000..a11f36305 Binary files /dev/null and b/en/pe-docs/docs/assets/img/cost-optimization/memory_metrics.png differ diff --git a/en/pe-docs/docs/assets/img/cost-optimization/monthly_cost.png b/en/pe-docs/docs/assets/img/cost-optimization/monthly_cost.png new file mode 100644 index 000000000..be59b09f6 Binary files /dev/null and b/en/pe-docs/docs/assets/img/cost-optimization/monthly_cost.png differ diff --git a/en/pe-docs/docs/assets/img/cost-optimization/monthly_missed_savings.png b/en/pe-docs/docs/assets/img/cost-optimization/monthly_missed_savings.png new file mode 100644 index 000000000..0b7785963 Binary files /dev/null and b/en/pe-docs/docs/assets/img/cost-optimization/monthly_missed_savings.png differ diff --git a/en/pe-docs/docs/assets/img/cost-optimization/monthly_savings_summary.png b/en/pe-docs/docs/assets/img/cost-optimization/monthly_savings_summary.png new file mode 100644 index 000000000..caa1b259f Binary files /dev/null and b/en/pe-docs/docs/assets/img/cost-optimization/monthly_savings_summary.png differ diff --git a/en/pe-docs/docs/assets/img/cost-optimization/project_summary.png b/en/pe-docs/docs/assets/img/cost-optimization/project_summary.png new file mode 100644 index 000000000..24ca956b6 Binary files /dev/null and b/en/pe-docs/docs/assets/img/cost-optimization/project_summary.png differ diff --git a/en/pe-docs/docs/assets/img/cost-optimization/recommendations.png b/en/pe-docs/docs/assets/img/cost-optimization/recommendations.png new file mode 100644 index 000000000..4aa2d73bd Binary files /dev/null and b/en/pe-docs/docs/assets/img/cost-optimization/recommendations.png differ diff --git a/en/pe-docs/docs/assets/img/cost-optimization/release_selection.png b/en/pe-docs/docs/assets/img/cost-optimization/release_selection.png new file mode 100644 index 000000000..039675b0c Binary files /dev/null and b/en/pe-docs/docs/assets/img/cost-optimization/release_selection.png differ diff --git a/en/pe-docs/docs/assets/img/cost-optimization/resource_efficiency.png b/en/pe-docs/docs/assets/img/cost-optimization/resource_efficiency.png new file mode 100644 index 000000000..463f1021d Binary files /dev/null and b/en/pe-docs/docs/assets/img/cost-optimization/resource_efficiency.png differ diff --git a/en/pe-docs/docs/assets/img/cost-optimization/total_monthly_savings.png b/en/pe-docs/docs/assets/img/cost-optimization/total_monthly_savings.png new file mode 100644 index 000000000..1de1c63d8 Binary files /dev/null and b/en/pe-docs/docs/assets/img/cost-optimization/total_monthly_savings.png differ diff --git a/en/site/assets/img/develop-components/deploy/authz-choreo-github-app.png b/en/pe-docs/docs/assets/img/develop-components/deploy/authz-choreo-github-app.png similarity index 100% rename from en/site/assets/img/develop-components/deploy/authz-choreo-github-app.png rename to en/pe-docs/docs/assets/img/develop-components/deploy/authz-choreo-github-app.png diff --git a/en/site/assets/img/develop-components/deploy/build-deploy-page-logs.png b/en/pe-docs/docs/assets/img/develop-components/deploy/build-deploy-page-logs.png similarity index 100% rename from en/site/assets/img/develop-components/deploy/build-deploy-page-logs.png rename to en/pe-docs/docs/assets/img/develop-components/deploy/build-deploy-page-logs.png diff --git a/en/site/assets/img/develop-components/deploy/build-deploy-page.png b/en/pe-docs/docs/assets/img/develop-components/deploy/build-deploy-page.png similarity index 100% rename from en/site/assets/img/develop-components/deploy/build-deploy-page.png rename to en/pe-docs/docs/assets/img/develop-components/deploy/build-deploy-page.png diff --git a/en/site/assets/img/develop-components/deploy/create-component-authz-github-page.png b/en/pe-docs/docs/assets/img/develop-components/deploy/create-component-authz-github-page.png similarity index 100% rename from en/site/assets/img/develop-components/deploy/create-component-authz-github-page.png rename to en/pe-docs/docs/assets/img/develop-components/deploy/create-component-authz-github-page.png diff --git a/en/site/assets/img/develop-components/deploy/create-component-connected-repo.png b/en/pe-docs/docs/assets/img/develop-components/deploy/create-component-connected-repo.png similarity index 100% rename from en/site/assets/img/develop-components/deploy/create-component-connected-repo.png rename to en/pe-docs/docs/assets/img/develop-components/deploy/create-component-connected-repo.png diff --git a/en/site/assets/img/develop-components/deploy/deploy-app-config-file-mount.png b/en/pe-docs/docs/assets/img/develop-components/deploy/deploy-app-config-file-mount.png similarity index 100% rename from en/site/assets/img/develop-components/deploy/deploy-app-config-file-mount.png rename to en/pe-docs/docs/assets/img/develop-components/deploy/deploy-app-config-file-mount.png diff --git a/en/site/assets/img/develop-components/deploy/deploy-app-config-page.png b/en/pe-docs/docs/assets/img/develop-components/deploy/deploy-app-config-page.png similarity index 100% rename from en/site/assets/img/develop-components/deploy/deploy-app-config-page.png rename to en/pe-docs/docs/assets/img/develop-components/deploy/deploy-app-config-page.png diff --git a/en/site/assets/img/develop-components/deploy/deploy-app-config-type-mount-page.png b/en/pe-docs/docs/assets/img/develop-components/deploy/deploy-app-config-type-mount-page.png similarity index 100% rename from en/site/assets/img/develop-components/deploy/deploy-app-config-type-mount-page.png rename to en/pe-docs/docs/assets/img/develop-components/deploy/deploy-app-config-type-mount-page.png diff --git a/en/site/assets/img/develop-components/deploy/github-repo-access.png b/en/pe-docs/docs/assets/img/develop-components/deploy/github-repo-access.png similarity index 100% rename from en/site/assets/img/develop-components/deploy/github-repo-access.png rename to en/pe-docs/docs/assets/img/develop-components/deploy/github-repo-access.png diff --git a/en/site/assets/img/develop-components/develop-a-rest-api-proxy/rest-api-proxy-response.png b/en/pe-docs/docs/assets/img/develop-components/develop-a-rest-api-proxy/rest-api-proxy-response.png similarity index 100% rename from en/site/assets/img/develop-components/develop-a-rest-api-proxy/rest-api-proxy-response.png rename to en/pe-docs/docs/assets/img/develop-components/develop-a-rest-api-proxy/rest-api-proxy-response.png diff --git a/en/site/assets/img/develop-components/develop-a-rest-api-proxy/try-out-response.png b/en/pe-docs/docs/assets/img/develop-components/develop-a-rest-api-proxy/try-out-response.png similarity index 100% rename from en/site/assets/img/develop-components/develop-a-rest-api-proxy/try-out-response.png rename to en/pe-docs/docs/assets/img/develop-components/develop-a-rest-api-proxy/try-out-response.png diff --git a/en/site/assets/img/develop-components/develop-a-scheduled-integration/Received-email.png b/en/pe-docs/docs/assets/img/develop-components/develop-a-scheduled-integration/Received-email.png similarity index 100% rename from en/site/assets/img/develop-components/develop-a-scheduled-integration/Received-email.png rename to en/pe-docs/docs/assets/img/develop-components/develop-a-scheduled-integration/Received-email.png diff --git a/en/site/assets/img/develop-components/develop-a-scheduled-integration/configurable-variable-as-a-secret.png b/en/pe-docs/docs/assets/img/develop-components/develop-a-scheduled-integration/configurable-variable-as-a-secret.png similarity index 100% rename from en/site/assets/img/develop-components/develop-a-scheduled-integration/configurable-variable-as-a-secret.png rename to en/pe-docs/docs/assets/img/develop-components/develop-a-scheduled-integration/configurable-variable-as-a-secret.png diff --git a/en/site/assets/img/develop-components/develop-a-scheduled-integration/execution_history.png b/en/pe-docs/docs/assets/img/develop-components/develop-a-scheduled-integration/execution_history.png similarity index 100% rename from en/site/assets/img/develop-components/develop-a-scheduled-integration/execution_history.png rename to en/pe-docs/docs/assets/img/develop-components/develop-a-scheduled-integration/execution_history.png diff --git a/en/site/assets/img/develop-components/develop-a-scheduled-integration/execution_logs.png b/en/pe-docs/docs/assets/img/develop-components/develop-a-scheduled-integration/execution_logs.png similarity index 100% rename from en/site/assets/img/develop-components/develop-a-scheduled-integration/execution_logs.png rename to en/pe-docs/docs/assets/img/develop-components/develop-a-scheduled-integration/execution_logs.png diff --git a/en/site/assets/img/develop-components/develop-a-scheduled-integration/total_executions.png b/en/pe-docs/docs/assets/img/develop-components/develop-a-scheduled-integration/total_executions.png similarity index 100% rename from en/site/assets/img/develop-components/develop-a-scheduled-integration/total_executions.png rename to en/pe-docs/docs/assets/img/develop-components/develop-a-scheduled-integration/total_executions.png diff --git a/en/site/assets/img/develop-components/develop-a-scheduled-integration/update-secret.png b/en/pe-docs/docs/assets/img/develop-components/develop-a-scheduled-integration/update-secret.png similarity index 100% rename from en/site/assets/img/develop-components/develop-a-scheduled-integration/update-secret.png rename to en/pe-docs/docs/assets/img/develop-components/develop-a-scheduled-integration/update-secret.png diff --git a/en/site/assets/img/develop-components/develop-using-vs-code/clone-a-project.gif b/en/pe-docs/docs/assets/img/develop-components/develop-using-vs-code/clone-a-project.gif similarity index 100% rename from en/site/assets/img/develop-components/develop-using-vs-code/clone-a-project.gif rename to en/pe-docs/docs/assets/img/develop-components/develop-using-vs-code/clone-a-project.gif diff --git a/en/site/assets/img/develop-components/develop-using-vs-code/component-details-view.png b/en/pe-docs/docs/assets/img/develop-components/develop-using-vs-code/component-details-view.png similarity index 100% rename from en/site/assets/img/develop-components/develop-using-vs-code/component-details-view.png rename to en/pe-docs/docs/assets/img/develop-components/develop-using-vs-code/component-details-view.png diff --git a/en/site/assets/img/develop-components/develop-using-vs-code/component-form.png b/en/pe-docs/docs/assets/img/develop-components/develop-using-vs-code/component-form.png similarity index 100% rename from en/site/assets/img/develop-components/develop-using-vs-code/component-form.png rename to en/pe-docs/docs/assets/img/develop-components/develop-using-vs-code/component-form.png diff --git a/en/site/assets/img/develop-components/develop-using-vs-code/create-a-component.gif b/en/pe-docs/docs/assets/img/develop-components/develop-using-vs-code/create-a-component.gif similarity index 100% rename from en/site/assets/img/develop-components/develop-using-vs-code/create-a-component.gif rename to en/pe-docs/docs/assets/img/develop-components/develop-using-vs-code/create-a-component.gif diff --git a/en/site/assets/img/develop-components/develop-using-vs-code/create-a-project.gif b/en/pe-docs/docs/assets/img/develop-components/develop-using-vs-code/create-a-project.gif similarity index 100% rename from en/site/assets/img/develop-components/develop-using-vs-code/create-a-project.gif rename to en/pe-docs/docs/assets/img/develop-components/develop-using-vs-code/create-a-project.gif diff --git a/en/site/assets/img/develop-components/develop-using-vs-code/create-component-btn.png b/en/pe-docs/docs/assets/img/develop-components/develop-using-vs-code/create-component-btn.png similarity index 100% rename from en/site/assets/img/develop-components/develop-using-vs-code/create-component-btn.png rename to en/pe-docs/docs/assets/img/develop-components/develop-using-vs-code/create-component-btn.png diff --git a/en/site/assets/img/develop-components/develop-using-vs-code/create-project-tree-view.png b/en/pe-docs/docs/assets/img/develop-components/develop-using-vs-code/create-project-tree-view.png similarity index 100% rename from en/site/assets/img/develop-components/develop-using-vs-code/create-project-tree-view.png rename to en/pe-docs/docs/assets/img/develop-components/develop-using-vs-code/create-project-tree-view.png diff --git a/en/site/assets/img/develop-components/develop-using-vs-code/link-dir-btn.png b/en/pe-docs/docs/assets/img/develop-components/develop-using-vs-code/link-dir-btn.png similarity index 100% rename from en/site/assets/img/develop-components/develop-using-vs-code/link-dir-btn.png rename to en/pe-docs/docs/assets/img/develop-components/develop-using-vs-code/link-dir-btn.png diff --git a/en/site/assets/img/develop-components/develop-using-vs-code/projects-and-orgs.png b/en/pe-docs/docs/assets/img/develop-components/develop-using-vs-code/projects-and-orgs.png similarity index 100% rename from en/site/assets/img/develop-components/develop-using-vs-code/projects-and-orgs.png rename to en/pe-docs/docs/assets/img/develop-components/develop-using-vs-code/projects-and-orgs.png diff --git a/en/site/assets/img/develop-components/develop-using-vs-code/push-changes.gif b/en/pe-docs/docs/assets/img/develop-components/develop-using-vs-code/push-changes.gif similarity index 100% rename from en/site/assets/img/develop-components/develop-using-vs-code/push-changes.gif rename to en/pe-docs/docs/assets/img/develop-components/develop-using-vs-code/push-changes.gif diff --git a/en/site/assets/img/develop-components/develop-using-vs-code/sign-in.png b/en/pe-docs/docs/assets/img/develop-components/develop-using-vs-code/sign-in.png similarity index 100% rename from en/site/assets/img/develop-components/develop-using-vs-code/sign-in.png rename to en/pe-docs/docs/assets/img/develop-components/develop-using-vs-code/sign-in.png diff --git a/en/site/assets/img/develop-components/micro-integrator/add-server.png b/en/pe-docs/docs/assets/img/develop-components/micro-integrator/add-server.png similarity index 100% rename from en/site/assets/img/develop-components/micro-integrator/add-server.png rename to en/pe-docs/docs/assets/img/develop-components/micro-integrator/add-server.png diff --git a/en/site/assets/img/develop-components/micro-integrator/click_change_runtime.png b/en/pe-docs/docs/assets/img/develop-components/micro-integrator/click_change_runtime.png similarity index 100% rename from en/site/assets/img/develop-components/micro-integrator/click_change_runtime.png rename to en/pe-docs/docs/assets/img/develop-components/micro-integrator/click_change_runtime.png diff --git a/en/site/assets/img/develop-components/micro-integrator/config_file.png b/en/pe-docs/docs/assets/img/develop-components/micro-integrator/config_file.png similarity index 100% rename from en/site/assets/img/develop-components/micro-integrator/config_file.png rename to en/pe-docs/docs/assets/img/develop-components/micro-integrator/config_file.png diff --git a/en/site/assets/img/develop-components/micro-integrator/define-a-remote-server-instance.png b/en/pe-docs/docs/assets/img/develop-components/micro-integrator/define-a-remote-server-instance.png similarity index 100% rename from en/site/assets/img/develop-components/micro-integrator/define-a-remote-server-instance.png rename to en/pe-docs/docs/assets/img/develop-components/micro-integrator/define-a-remote-server-instance.png diff --git a/en/site/assets/img/develop-components/micro-integrator/env_variables.png b/en/pe-docs/docs/assets/img/develop-components/micro-integrator/env_variables.png similarity index 100% rename from en/site/assets/img/develop-components/micro-integrator/env_variables.png rename to en/pe-docs/docs/assets/img/develop-components/micro-integrator/env_variables.png diff --git a/en/site/assets/img/develop-components/micro-integrator/libs_dir.png b/en/pe-docs/docs/assets/img/develop-components/micro-integrator/libs_dir.png similarity index 100% rename from en/site/assets/img/develop-components/micro-integrator/libs_dir.png rename to en/pe-docs/docs/assets/img/develop-components/micro-integrator/libs_dir.png diff --git a/en/site/assets/img/develop-components/micro-integrator/openapi_file.png b/en/pe-docs/docs/assets/img/develop-components/micro-integrator/openapi_file.png similarity index 100% rename from en/site/assets/img/develop-components/micro-integrator/openapi_file.png rename to en/pe-docs/docs/assets/img/develop-components/micro-integrator/openapi_file.png diff --git a/en/site/assets/img/develop-components/micro-integrator/project-runtime-version.png b/en/pe-docs/docs/assets/img/develop-components/micro-integrator/project-runtime-version.png similarity index 100% rename from en/site/assets/img/develop-components/micro-integrator/project-runtime-version.png rename to en/pe-docs/docs/assets/img/develop-components/micro-integrator/project-runtime-version.png diff --git a/en/site/assets/img/develop-components/micro-integrator/redeploy-project.png b/en/pe-docs/docs/assets/img/develop-components/micro-integrator/redeploy-project.png similarity index 100% rename from en/site/assets/img/develop-components/micro-integrator/redeploy-project.png rename to en/pe-docs/docs/assets/img/develop-components/micro-integrator/redeploy-project.png diff --git a/en/site/assets/img/develop-components/micro-integrator/runtime_version_in_logs.png b/en/pe-docs/docs/assets/img/develop-components/micro-integrator/runtime_version_in_logs.png similarity index 100% rename from en/site/assets/img/develop-components/micro-integrator/runtime_version_in_logs.png rename to en/pe-docs/docs/assets/img/develop-components/micro-integrator/runtime_version_in_logs.png diff --git a/en/site/assets/img/develop-components/micro-integrator/set-server-url.png b/en/pe-docs/docs/assets/img/develop-components/micro-integrator/set-server-url.png similarity index 100% rename from en/site/assets/img/develop-components/micro-integrator/set-server-url.png rename to en/pe-docs/docs/assets/img/develop-components/micro-integrator/set-server-url.png diff --git a/en/site/assets/img/develop-components/micro-integrator/specify_runtime_version.png b/en/pe-docs/docs/assets/img/develop-components/micro-integrator/specify_runtime_version.png similarity index 100% rename from en/site/assets/img/develop-components/micro-integrator/specify_runtime_version.png rename to en/pe-docs/docs/assets/img/develop-components/micro-integrator/specify_runtime_version.png diff --git a/en/site/assets/img/develop-components/micro-integrator/update_runtime_version.png b/en/pe-docs/docs/assets/img/develop-components/micro-integrator/update_runtime_version.png similarity index 100% rename from en/site/assets/img/develop-components/micro-integrator/update_runtime_version.png rename to en/pe-docs/docs/assets/img/develop-components/micro-integrator/update_runtime_version.png diff --git a/en/site/assets/img/develop-components/micro-integrator/version-string.png b/en/pe-docs/docs/assets/img/develop-components/micro-integrator/version-string.png similarity index 100% rename from en/site/assets/img/develop-components/micro-integrator/version-string.png rename to en/pe-docs/docs/assets/img/develop-components/micro-integrator/version-string.png diff --git a/en/site/assets/img/devops-and-ci-cd/configs/create-env-vars.png b/en/pe-docs/docs/assets/img/devops-and-ci-cd/configs/create-env-vars.png similarity index 100% rename from en/site/assets/img/devops-and-ci-cd/configs/create-env-vars.png rename to en/pe-docs/docs/assets/img/devops-and-ci-cd/configs/create-env-vars.png diff --git a/en/site/assets/img/devops-and-ci-cd/configs/create-file-mount.png b/en/pe-docs/docs/assets/img/devops-and-ci-cd/configs/create-file-mount.png similarity index 100% rename from en/site/assets/img/devops-and-ci-cd/configs/create-file-mount.png rename to en/pe-docs/docs/assets/img/devops-and-ci-cd/configs/create-file-mount.png diff --git a/en/site/assets/img/devops-and-ci-cd/configs/create-or-delete-config.png b/en/pe-docs/docs/assets/img/devops-and-ci-cd/configs/create-or-delete-config.png similarity index 100% rename from en/site/assets/img/devops-and-ci-cd/configs/create-or-delete-config.png rename to en/pe-docs/docs/assets/img/devops-and-ci-cd/configs/create-or-delete-config.png diff --git a/en/site/assets/img/devops-and-ci-cd/containers/containers-view.png b/en/pe-docs/docs/assets/img/devops-and-ci-cd/containers/containers-view.png similarity index 100% rename from en/site/assets/img/devops-and-ci-cd/containers/containers-view.png rename to en/pe-docs/docs/assets/img/devops-and-ci-cd/containers/containers-view.png diff --git a/en/site/assets/img/devops-and-ci-cd/containers/edit-container-form.png b/en/pe-docs/docs/assets/img/devops-and-ci-cd/containers/edit-container-form.png similarity index 100% rename from en/site/assets/img/devops-and-ci-cd/containers/edit-container-form.png rename to en/pe-docs/docs/assets/img/devops-and-ci-cd/containers/edit-container-form.png diff --git a/en/site/assets/img/devops-and-ci-cd/containers/example-container-cmd-and-args.png b/en/pe-docs/docs/assets/img/devops-and-ci-cd/containers/example-container-cmd-and-args.png similarity index 100% rename from en/site/assets/img/devops-and-ci-cd/containers/example-container-cmd-and-args.png rename to en/pe-docs/docs/assets/img/devops-and-ci-cd/containers/example-container-cmd-and-args.png diff --git a/en/site/assets/img/devops-and-ci-cd/healthchecks/confgure-probes.png b/en/pe-docs/docs/assets/img/devops-and-ci-cd/healthchecks/confgure-probes.png similarity index 100% rename from en/site/assets/img/devops-and-ci-cd/healthchecks/confgure-probes.png rename to en/pe-docs/docs/assets/img/devops-and-ci-cd/healthchecks/confgure-probes.png diff --git a/en/site/assets/img/devops-and-ci-cd/healthchecks/http-get-probe.png b/en/pe-docs/docs/assets/img/devops-and-ci-cd/healthchecks/http-get-probe.png similarity index 100% rename from en/site/assets/img/devops-and-ci-cd/healthchecks/http-get-probe.png rename to en/pe-docs/docs/assets/img/devops-and-ci-cd/healthchecks/http-get-probe.png diff --git a/en/site/assets/img/devops-and-ci-cd/runtime/container-conditions-and-events.png b/en/pe-docs/docs/assets/img/devops-and-ci-cd/runtime/container-conditions-and-events.png similarity index 100% rename from en/site/assets/img/devops-and-ci-cd/runtime/container-conditions-and-events.png rename to en/pe-docs/docs/assets/img/devops-and-ci-cd/runtime/container-conditions-and-events.png diff --git a/en/site/assets/img/devops-and-ci-cd/runtime/realtime-container-logs.png b/en/pe-docs/docs/assets/img/devops-and-ci-cd/runtime/realtime-container-logs.png similarity index 100% rename from en/site/assets/img/devops-and-ci-cd/runtime/realtime-container-logs.png rename to en/pe-docs/docs/assets/img/devops-and-ci-cd/runtime/realtime-container-logs.png diff --git a/en/site/assets/img/devops-and-ci-cd/runtime/running-instaces.png b/en/pe-docs/docs/assets/img/devops-and-ci-cd/runtime/running-instaces.png similarity index 100% rename from en/site/assets/img/devops-and-ci-cd/runtime/running-instaces.png rename to en/pe-docs/docs/assets/img/devops-and-ci-cd/runtime/running-instaces.png diff --git a/en/site/assets/img/devops-and-ci-cd/runtime/runtime-view.png b/en/pe-docs/docs/assets/img/devops-and-ci-cd/runtime/runtime-view.png similarity index 100% rename from en/site/assets/img/devops-and-ci-cd/runtime/runtime-view.png rename to en/pe-docs/docs/assets/img/devops-and-ci-cd/runtime/runtime-view.png diff --git a/en/site/assets/img/devops-and-ci-cd/scaling/free-user-scaling-view.png b/en/pe-docs/docs/assets/img/devops-and-ci-cd/scaling/free-user-scaling-view.png similarity index 100% rename from en/site/assets/img/devops-and-ci-cd/scaling/free-user-scaling-view.png rename to en/pe-docs/docs/assets/img/devops-and-ci-cd/scaling/free-user-scaling-view.png diff --git a/en/site/assets/img/devops-and-ci-cd/scaling/paid-user-scaling-view.png b/en/pe-docs/docs/assets/img/devops-and-ci-cd/scaling/paid-user-scaling-view.png similarity index 100% rename from en/site/assets/img/devops-and-ci-cd/scaling/paid-user-scaling-view.png rename to en/pe-docs/docs/assets/img/devops-and-ci-cd/scaling/paid-user-scaling-view.png diff --git a/en/site/assets/img/devops-and-ci-cd/scaling/scale-to-zero-in-deploy-view.png b/en/pe-docs/docs/assets/img/devops-and-ci-cd/scaling/scale-to-zero-in-deploy-view.png similarity index 100% rename from en/site/assets/img/devops-and-ci-cd/scaling/scale-to-zero-in-deploy-view.png rename to en/pe-docs/docs/assets/img/devops-and-ci-cd/scaling/scale-to-zero-in-deploy-view.png diff --git a/en/site/assets/img/devops-and-ci-cd/scaling/scale-to-zero-view.png b/en/pe-docs/docs/assets/img/devops-and-ci-cd/scaling/scale-to-zero-view.png similarity index 100% rename from en/site/assets/img/devops-and-ci-cd/scaling/scale-to-zero-view.png rename to en/pe-docs/docs/assets/img/devops-and-ci-cd/scaling/scale-to-zero-view.png diff --git a/en/site/assets/img/devops-and-ci-cd/scaling/scaling-view.png b/en/pe-docs/docs/assets/img/devops-and-ci-cd/scaling/scaling-view.png similarity index 100% rename from en/site/assets/img/devops-and-ci-cd/scaling/scaling-view.png rename to en/pe-docs/docs/assets/img/devops-and-ci-cd/scaling/scaling-view.png diff --git a/en/site/assets/img/devops-and-ci-cd/storage/create-emptydir-step-1.png b/en/pe-docs/docs/assets/img/devops-and-ci-cd/storage/create-emptydir-step-1.png similarity index 100% rename from en/site/assets/img/devops-and-ci-cd/storage/create-emptydir-step-1.png rename to en/pe-docs/docs/assets/img/devops-and-ci-cd/storage/create-emptydir-step-1.png diff --git a/en/site/assets/img/devops-and-ci-cd/storage/create-emptydir-step-2.png b/en/pe-docs/docs/assets/img/devops-and-ci-cd/storage/create-emptydir-step-2.png similarity index 100% rename from en/site/assets/img/devops-and-ci-cd/storage/create-emptydir-step-2.png rename to en/pe-docs/docs/assets/img/devops-and-ci-cd/storage/create-emptydir-step-2.png diff --git a/en/site/assets/img/devops-and-ci-cd/storage/create-pv.png b/en/pe-docs/docs/assets/img/devops-and-ci-cd/storage/create-pv.png similarity index 100% rename from en/site/assets/img/devops-and-ci-cd/storage/create-pv.png rename to en/pe-docs/docs/assets/img/devops-and-ci-cd/storage/create-pv.png diff --git a/en/site/assets/img/devops-and-ci-cd/tailscale/deployment-architecture.png b/en/pe-docs/docs/assets/img/devops-and-ci-cd/tailscale/deployment-architecture.png similarity index 100% rename from en/site/assets/img/devops-and-ci-cd/tailscale/deployment-architecture.png rename to en/pe-docs/docs/assets/img/devops-and-ci-cd/tailscale/deployment-architecture.png diff --git a/en/site/assets/img/devops-and-ci-cd/tailscale/tailscale-proxy-deployment.png b/en/pe-docs/docs/assets/img/devops-and-ci-cd/tailscale/tailscale-proxy-deployment.png similarity index 100% rename from en/site/assets/img/devops-and-ci-cd/tailscale/tailscale-proxy-deployment.png rename to en/pe-docs/docs/assets/img/devops-and-ci-cd/tailscale/tailscale-proxy-deployment.png diff --git a/en/site/assets/img/home/api.svg b/en/pe-docs/docs/assets/img/home/api.svg similarity index 100% rename from en/site/assets/img/home/api.svg rename to en/pe-docs/docs/assets/img/home/api.svg diff --git a/en/site/assets/img/home/background.svg b/en/pe-docs/docs/assets/img/home/background.svg similarity index 100% rename from en/site/assets/img/home/background.svg rename to en/pe-docs/docs/assets/img/home/background.svg diff --git a/en/site/assets/img/home/integrations.svg b/en/pe-docs/docs/assets/img/home/integrations.svg similarity index 100% rename from en/site/assets/img/home/integrations.svg rename to en/pe-docs/docs/assets/img/home/integrations.svg diff --git a/en/site/assets/img/home/services.svg b/en/pe-docs/docs/assets/img/home/services.svg similarity index 100% rename from en/site/assets/img/home/services.svg rename to en/pe-docs/docs/assets/img/home/services.svg diff --git a/en/site/assets/img/logo.png b/en/pe-docs/docs/assets/img/logo.png similarity index 100% rename from en/site/assets/img/logo.png rename to en/pe-docs/docs/assets/img/logo.png diff --git a/en/pe-docs/docs/assets/img/monitoring-and-insights/alerts/alert-creation.png b/en/pe-docs/docs/assets/img/monitoring-and-insights/alerts/alert-creation.png new file mode 100644 index 000000000..c076e56d3 Binary files /dev/null and b/en/pe-docs/docs/assets/img/monitoring-and-insights/alerts/alert-creation.png differ diff --git a/en/pe-docs/docs/assets/img/monitoring-and-insights/alerts/email-notification.png b/en/pe-docs/docs/assets/img/monitoring-and-insights/alerts/email-notification.png new file mode 100644 index 000000000..229c6c5b9 Binary files /dev/null and b/en/pe-docs/docs/assets/img/monitoring-and-insights/alerts/email-notification.png differ diff --git a/en/site/assets/img/monitoring-and-insights/api-insights/alert-summary.png b/en/pe-docs/docs/assets/img/monitoring-and-insights/api-insights/alert-summary.png similarity index 100% rename from en/site/assets/img/monitoring-and-insights/api-insights/alert-summary.png rename to en/pe-docs/docs/assets/img/monitoring-and-insights/api-insights/alert-summary.png diff --git a/en/site/assets/img/monitoring-and-insights/api-insights/alerts-page-full.png b/en/pe-docs/docs/assets/img/monitoring-and-insights/api-insights/alerts-page-full.png similarity index 100% rename from en/site/assets/img/monitoring-and-insights/api-insights/alerts-page-full.png rename to en/pe-docs/docs/assets/img/monitoring-and-insights/api-insights/alerts-page-full.png diff --git a/en/site/assets/img/monitoring-and-insights/api-insights/api-usage-timeline.png b/en/pe-docs/docs/assets/img/monitoring-and-insights/api-insights/api-usage-timeline.png similarity index 100% rename from en/site/assets/img/monitoring-and-insights/api-insights/api-usage-timeline.png rename to en/pe-docs/docs/assets/img/monitoring-and-insights/api-insights/api-usage-timeline.png diff --git a/en/site/assets/img/monitoring-and-insights/api-insights/cache-latency.png b/en/pe-docs/docs/assets/img/monitoring-and-insights/api-insights/cache-latency.png similarity index 100% rename from en/site/assets/img/monitoring-and-insights/api-insights/cache-latency.png rename to en/pe-docs/docs/assets/img/monitoring-and-insights/api-insights/cache-latency.png diff --git a/en/site/assets/img/monitoring-and-insights/api-insights/cache-page-full.png b/en/pe-docs/docs/assets/img/monitoring-and-insights/api-insights/cache-page-full.png similarity index 100% rename from en/site/assets/img/monitoring-and-insights/api-insights/cache-page-full.png rename to en/pe-docs/docs/assets/img/monitoring-and-insights/api-insights/cache-page-full.png diff --git a/en/site/assets/img/monitoring-and-insights/api-insights/cache-statistics.png b/en/pe-docs/docs/assets/img/monitoring-and-insights/api-insights/cache-statistics.png similarity index 100% rename from en/site/assets/img/monitoring-and-insights/api-insights/cache-statistics.png rename to en/pe-docs/docs/assets/img/monitoring-and-insights/api-insights/cache-statistics.png diff --git a/en/site/assets/img/monitoring-and-insights/api-insights/choreo-system-home.png b/en/pe-docs/docs/assets/img/monitoring-and-insights/api-insights/choreo-system-home.png similarity index 100% rename from en/site/assets/img/monitoring-and-insights/api-insights/choreo-system-home.png rename to en/pe-docs/docs/assets/img/monitoring-and-insights/api-insights/choreo-system-home.png diff --git a/en/site/assets/img/monitoring-and-insights/api-insights/configured-report.png b/en/pe-docs/docs/assets/img/monitoring-and-insights/api-insights/configured-report.png similarity index 100% rename from en/site/assets/img/monitoring-and-insights/api-insights/configured-report.png rename to en/pe-docs/docs/assets/img/monitoring-and-insights/api-insights/configured-report.png diff --git a/en/site/assets/img/monitoring-and-insights/api-insights/create-application-wizard.png b/en/pe-docs/docs/assets/img/monitoring-and-insights/api-insights/create-application-wizard.png similarity index 100% rename from en/site/assets/img/monitoring-and-insights/api-insights/create-application-wizard.png rename to en/pe-docs/docs/assets/img/monitoring-and-insights/api-insights/create-application-wizard.png diff --git a/en/site/assets/img/monitoring-and-insights/api-insights/create-application.png b/en/pe-docs/docs/assets/img/monitoring-and-insights/api-insights/create-application.png similarity index 100% rename from en/site/assets/img/monitoring-and-insights/api-insights/create-application.png rename to en/pe-docs/docs/assets/img/monitoring-and-insights/api-insights/create-application.png diff --git a/en/site/assets/img/monitoring-and-insights/api-insights/custom-report-sample.png b/en/pe-docs/docs/assets/img/monitoring-and-insights/api-insights/custom-report-sample.png similarity index 100% rename from en/site/assets/img/monitoring-and-insights/api-insights/custom-report-sample.png rename to en/pe-docs/docs/assets/img/monitoring-and-insights/api-insights/custom-report-sample.png diff --git a/en/site/assets/img/monitoring-and-insights/api-insights/custom-report.png b/en/pe-docs/docs/assets/img/monitoring-and-insights/api-insights/custom-report.png similarity index 100% rename from en/site/assets/img/monitoring-and-insights/api-insights/custom-report.png rename to en/pe-docs/docs/assets/img/monitoring-and-insights/api-insights/custom-report.png diff --git a/en/site/assets/img/monitoring-and-insights/api-insights/custom-reports-step-1.png b/en/pe-docs/docs/assets/img/monitoring-and-insights/api-insights/custom-reports-step-1.png similarity index 100% rename from en/site/assets/img/monitoring-and-insights/api-insights/custom-reports-step-1.png rename to en/pe-docs/docs/assets/img/monitoring-and-insights/api-insights/custom-reports-step-1.png diff --git a/en/site/assets/img/monitoring-and-insights/api-insights/custom-reports-step-2-to-4.png b/en/pe-docs/docs/assets/img/monitoring-and-insights/api-insights/custom-reports-step-2-to-4.png similarity index 100% rename from en/site/assets/img/monitoring-and-insights/api-insights/custom-reports-step-2-to-4.png rename to en/pe-docs/docs/assets/img/monitoring-and-insights/api-insights/custom-reports-step-2-to-4.png diff --git a/en/site/assets/img/monitoring-and-insights/api-insights/custom-reports-step-5.png b/en/pe-docs/docs/assets/img/monitoring-and-insights/api-insights/custom-reports-step-5.png similarity index 100% rename from en/site/assets/img/monitoring-and-insights/api-insights/custom-reports-step-5.png rename to en/pe-docs/docs/assets/img/monitoring-and-insights/api-insights/custom-reports-step-5.png diff --git a/en/site/assets/img/monitoring-and-insights/api-insights/custom-reports-step-6.png b/en/pe-docs/docs/assets/img/monitoring-and-insights/api-insights/custom-reports-step-6.png similarity index 100% rename from en/site/assets/img/monitoring-and-insights/api-insights/custom-reports-step-6.png rename to en/pe-docs/docs/assets/img/monitoring-and-insights/api-insights/custom-reports-step-6.png diff --git a/en/site/assets/img/monitoring-and-insights/api-insights/custom-reports-step-7.png b/en/pe-docs/docs/assets/img/monitoring-and-insights/api-insights/custom-reports-step-7.png similarity index 100% rename from en/site/assets/img/monitoring-and-insights/api-insights/custom-reports-step-7.png rename to en/pe-docs/docs/assets/img/monitoring-and-insights/api-insights/custom-reports-step-7.png diff --git a/en/site/assets/img/monitoring-and-insights/api-insights/devices-page-full.png b/en/pe-docs/docs/assets/img/monitoring-and-insights/api-insights/devices-page-full.png similarity index 100% rename from en/site/assets/img/monitoring-and-insights/api-insights/devices-page-full.png rename to en/pe-docs/docs/assets/img/monitoring-and-insights/api-insights/devices-page-full.png diff --git a/en/site/assets/img/monitoring-and-insights/api-insights/endpoints.png b/en/pe-docs/docs/assets/img/monitoring-and-insights/api-insights/endpoints.png similarity index 100% rename from en/site/assets/img/monitoring-and-insights/api-insights/endpoints.png rename to en/pe-docs/docs/assets/img/monitoring-and-insights/api-insights/endpoints.png diff --git a/en/site/assets/img/monitoring-and-insights/api-insights/error-by-status-code.png b/en/pe-docs/docs/assets/img/monitoring-and-insights/api-insights/error-by-status-code.png similarity index 100% rename from en/site/assets/img/monitoring-and-insights/api-insights/error-by-status-code.png rename to en/pe-docs/docs/assets/img/monitoring-and-insights/api-insights/error-by-status-code.png diff --git a/en/site/assets/img/monitoring-and-insights/api-insights/error-category-graph.png b/en/pe-docs/docs/assets/img/monitoring-and-insights/api-insights/error-category-graph.png similarity index 100% rename from en/site/assets/img/monitoring-and-insights/api-insights/error-category-graph.png rename to en/pe-docs/docs/assets/img/monitoring-and-insights/api-insights/error-category-graph.png diff --git a/en/site/assets/img/monitoring-and-insights/api-insights/error-category-table.png b/en/pe-docs/docs/assets/img/monitoring-and-insights/api-insights/error-category-table.png similarity index 100% rename from en/site/assets/img/monitoring-and-insights/api-insights/error-category-table.png rename to en/pe-docs/docs/assets/img/monitoring-and-insights/api-insights/error-category-table.png diff --git a/en/site/assets/img/monitoring-and-insights/api-insights/error-heatmap.png b/en/pe-docs/docs/assets/img/monitoring-and-insights/api-insights/error-heatmap.png similarity index 100% rename from en/site/assets/img/monitoring-and-insights/api-insights/error-heatmap.png rename to en/pe-docs/docs/assets/img/monitoring-and-insights/api-insights/error-heatmap.png diff --git a/en/site/assets/img/monitoring-and-insights/api-insights/error-page-full.png b/en/pe-docs/docs/assets/img/monitoring-and-insights/api-insights/error-page-full.png similarity index 100% rename from en/site/assets/img/monitoring-and-insights/api-insights/error-page-full.png rename to en/pe-docs/docs/assets/img/monitoring-and-insights/api-insights/error-page-full.png diff --git a/en/site/assets/img/monitoring-and-insights/api-insights/generate-credentials.png b/en/pe-docs/docs/assets/img/monitoring-and-insights/api-insights/generate-credentials.png similarity index 100% rename from en/site/assets/img/monitoring-and-insights/api-insights/generate-credentials.png rename to en/pe-docs/docs/assets/img/monitoring-and-insights/api-insights/generate-credentials.png diff --git a/en/site/assets/img/monitoring-and-insights/api-insights/geomap-hit-count-scale.png b/en/pe-docs/docs/assets/img/monitoring-and-insights/api-insights/geomap-hit-count-scale.png similarity index 100% rename from en/site/assets/img/monitoring-and-insights/api-insights/geomap-hit-count-scale.png rename to en/pe-docs/docs/assets/img/monitoring-and-insights/api-insights/geomap-hit-count-scale.png diff --git a/en/site/assets/img/monitoring-and-insights/api-insights/geomap-page-full.png b/en/pe-docs/docs/assets/img/monitoring-and-insights/api-insights/geomap-page-full.png similarity index 100% rename from en/site/assets/img/monitoring-and-insights/api-insights/geomap-page-full.png rename to en/pe-docs/docs/assets/img/monitoring-and-insights/api-insights/geomap-page-full.png diff --git a/en/site/assets/img/monitoring-and-insights/api-insights/geomap-requests-by-country.png b/en/pe-docs/docs/assets/img/monitoring-and-insights/api-insights/geomap-requests-by-country.png similarity index 100% rename from en/site/assets/img/monitoring-and-insights/api-insights/geomap-requests-by-country.png rename to en/pe-docs/docs/assets/img/monitoring-and-insights/api-insights/geomap-requests-by-country.png diff --git a/en/site/assets/img/monitoring-and-insights/api-insights/insights-download-report.svg b/en/pe-docs/docs/assets/img/monitoring-and-insights/api-insights/insights-download-report.svg similarity index 100% rename from en/site/assets/img/monitoring-and-insights/api-insights/insights-download-report.svg rename to en/pe-docs/docs/assets/img/monitoring-and-insights/api-insights/insights-download-report.svg diff --git a/en/site/assets/img/monitoring-and-insights/api-insights/latency-by-category.png b/en/pe-docs/docs/assets/img/monitoring-and-insights/api-insights/latency-by-category.png similarity index 100% rename from en/site/assets/img/monitoring-and-insights/api-insights/latency-by-category.png rename to en/pe-docs/docs/assets/img/monitoring-and-insights/api-insights/latency-by-category.png diff --git a/en/site/assets/img/monitoring-and-insights/api-insights/latency-page-full.png b/en/pe-docs/docs/assets/img/monitoring-and-insights/api-insights/latency-page-full.png similarity index 100% rename from en/site/assets/img/monitoring-and-insights/api-insights/latency-page-full.png rename to en/pe-docs/docs/assets/img/monitoring-and-insights/api-insights/latency-page-full.png diff --git a/en/site/assets/img/monitoring-and-insights/api-insights/overview-page-error-rate.png b/en/pe-docs/docs/assets/img/monitoring-and-insights/api-insights/overview-page-error-rate.png similarity index 100% rename from en/site/assets/img/monitoring-and-insights/api-insights/overview-page-error-rate.png rename to en/pe-docs/docs/assets/img/monitoring-and-insights/api-insights/overview-page-error-rate.png diff --git a/en/site/assets/img/monitoring-and-insights/api-insights/overview-page-error-request-count.png b/en/pe-docs/docs/assets/img/monitoring-and-insights/api-insights/overview-page-error-request-count.png similarity index 100% rename from en/site/assets/img/monitoring-and-insights/api-insights/overview-page-error-request-count.png rename to en/pe-docs/docs/assets/img/monitoring-and-insights/api-insights/overview-page-error-request-count.png diff --git a/en/site/assets/img/monitoring-and-insights/api-insights/overview-page-latency.png b/en/pe-docs/docs/assets/img/monitoring-and-insights/api-insights/overview-page-latency.png similarity index 100% rename from en/site/assets/img/monitoring-and-insights/api-insights/overview-page-latency.png rename to en/pe-docs/docs/assets/img/monitoring-and-insights/api-insights/overview-page-latency.png diff --git a/en/site/assets/img/monitoring-and-insights/api-insights/overview-page-timeline.png b/en/pe-docs/docs/assets/img/monitoring-and-insights/api-insights/overview-page-timeline.png similarity index 100% rename from en/site/assets/img/monitoring-and-insights/api-insights/overview-page-timeline.png rename to en/pe-docs/docs/assets/img/monitoring-and-insights/api-insights/overview-page-timeline.png diff --git a/en/site/assets/img/monitoring-and-insights/api-insights/overview-page-total-traffic.png b/en/pe-docs/docs/assets/img/monitoring-and-insights/api-insights/overview-page-total-traffic.png similarity index 100% rename from en/site/assets/img/monitoring-and-insights/api-insights/overview-page-total-traffic.png rename to en/pe-docs/docs/assets/img/monitoring-and-insights/api-insights/overview-page-total-traffic.png diff --git a/en/site/assets/img/monitoring-and-insights/api-insights/overview.png b/en/pe-docs/docs/assets/img/monitoring-and-insights/api-insights/overview.png similarity index 100% rename from en/site/assets/img/monitoring-and-insights/api-insights/overview.png rename to en/pe-docs/docs/assets/img/monitoring-and-insights/api-insights/overview.png diff --git a/en/site/assets/img/monitoring-and-insights/api-insights/report-page-full.png b/en/pe-docs/docs/assets/img/monitoring-and-insights/api-insights/report-page-full.png similarity index 100% rename from en/site/assets/img/monitoring-and-insights/api-insights/report-page-full.png rename to en/pe-docs/docs/assets/img/monitoring-and-insights/api-insights/report-page-full.png diff --git a/en/site/assets/img/monitoring-and-insights/api-insights/request-access.png b/en/pe-docs/docs/assets/img/monitoring-and-insights/api-insights/request-access.png similarity index 100% rename from en/site/assets/img/monitoring-and-insights/api-insights/request-access.png rename to en/pe-docs/docs/assets/img/monitoring-and-insights/api-insights/request-access.png diff --git a/en/site/assets/img/monitoring-and-insights/api-insights/resource-usage.png b/en/pe-docs/docs/assets/img/monitoring-and-insights/api-insights/resource-usage.png similarity index 100% rename from en/site/assets/img/monitoring-and-insights/api-insights/resource-usage.png rename to en/pe-docs/docs/assets/img/monitoring-and-insights/api-insights/resource-usage.png diff --git a/en/site/assets/img/monitoring-and-insights/api-insights/slowest-apis.png b/en/pe-docs/docs/assets/img/monitoring-and-insights/api-insights/slowest-apis.png similarity index 100% rename from en/site/assets/img/monitoring-and-insights/api-insights/slowest-apis.png rename to en/pe-docs/docs/assets/img/monitoring-and-insights/api-insights/slowest-apis.png diff --git a/en/site/assets/img/monitoring-and-insights/api-insights/subscribe-api.png b/en/pe-docs/docs/assets/img/monitoring-and-insights/api-insights/subscribe-api.png similarity index 100% rename from en/site/assets/img/monitoring-and-insights/api-insights/subscribe-api.png rename to en/pe-docs/docs/assets/img/monitoring-and-insights/api-insights/subscribe-api.png diff --git a/en/site/assets/img/monitoring-and-insights/api-insights/target-error-by-status-code.png b/en/pe-docs/docs/assets/img/monitoring-and-insights/api-insights/target-error-by-status-code.png similarity index 100% rename from en/site/assets/img/monitoring-and-insights/api-insights/target-error-by-status-code.png rename to en/pe-docs/docs/assets/img/monitoring-and-insights/api-insights/target-error-by-status-code.png diff --git a/en/site/assets/img/monitoring-and-insights/api-insights/target-error-heatmap.png b/en/pe-docs/docs/assets/img/monitoring-and-insights/api-insights/target-error-heatmap.png similarity index 100% rename from en/site/assets/img/monitoring-and-insights/api-insights/target-error-heatmap.png rename to en/pe-docs/docs/assets/img/monitoring-and-insights/api-insights/target-error-heatmap.png diff --git a/en/site/assets/img/monitoring-and-insights/api-insights/top-apis-by-alert-count.png b/en/pe-docs/docs/assets/img/monitoring-and-insights/api-insights/top-apis-by-alert-count.png similarity index 100% rename from en/site/assets/img/monitoring-and-insights/api-insights/top-apis-by-alert-count.png rename to en/pe-docs/docs/assets/img/monitoring-and-insights/api-insights/top-apis-by-alert-count.png diff --git a/en/site/assets/img/monitoring-and-insights/api-insights/top-platforms.png b/en/pe-docs/docs/assets/img/monitoring-and-insights/api-insights/top-platforms.png similarity index 100% rename from en/site/assets/img/monitoring-and-insights/api-insights/top-platforms.png rename to en/pe-docs/docs/assets/img/monitoring-and-insights/api-insights/top-platforms.png diff --git a/en/site/assets/img/monitoring-and-insights/api-insights/top-user-agents.png b/en/pe-docs/docs/assets/img/monitoring-and-insights/api-insights/top-user-agents.png similarity index 100% rename from en/site/assets/img/monitoring-and-insights/api-insights/top-user-agents.png rename to en/pe-docs/docs/assets/img/monitoring-and-insights/api-insights/top-user-agents.png diff --git a/en/site/assets/img/monitoring-and-insights/api-insights/traffic-page-full.png b/en/pe-docs/docs/assets/img/monitoring-and-insights/api-insights/traffic-page-full.png similarity index 100% rename from en/site/assets/img/monitoring-and-insights/api-insights/traffic-page-full.png rename to en/pe-docs/docs/assets/img/monitoring-and-insights/api-insights/traffic-page-full.png diff --git a/en/site/assets/img/monitoring-and-insights/api-insights/update-token-expirary-time.png b/en/pe-docs/docs/assets/img/monitoring-and-insights/api-insights/update-token-expirary-time.png similarity index 100% rename from en/site/assets/img/monitoring-and-insights/api-insights/update-token-expirary-time.png rename to en/pe-docs/docs/assets/img/monitoring-and-insights/api-insights/update-token-expirary-time.png diff --git a/en/site/assets/img/monitoring-and-insights/api-insights/usage-by-application.png b/en/pe-docs/docs/assets/img/monitoring-and-insights/api-insights/usage-by-application.png similarity index 100% rename from en/site/assets/img/monitoring-and-insights/api-insights/usage-by-application.png rename to en/pe-docs/docs/assets/img/monitoring-and-insights/api-insights/usage-by-application.png diff --git a/en/site/assets/img/monitoring-and-insights/api-insights/usage-by-target.png b/en/pe-docs/docs/assets/img/monitoring-and-insights/api-insights/usage-by-target.png similarity index 100% rename from en/site/assets/img/monitoring-and-insights/api-insights/usage-by-target.png rename to en/pe-docs/docs/assets/img/monitoring-and-insights/api-insights/usage-by-target.png diff --git a/en/site/assets/img/monitoring-and-insights/data_recieved_moesif_notification.png b/en/pe-docs/docs/assets/img/monitoring-and-insights/data_recieved_moesif_notification.png similarity index 100% rename from en/site/assets/img/monitoring-and-insights/data_recieved_moesif_notification.png rename to en/pe-docs/docs/assets/img/monitoring-and-insights/data_recieved_moesif_notification.png diff --git a/en/site/assets/img/monitoring-and-insights/engineering-insights/add-integration-cio-dashboard.png b/en/pe-docs/docs/assets/img/monitoring-and-insights/engineering-insights/add-integration-cio-dashboard.png similarity index 100% rename from en/site/assets/img/monitoring-and-insights/engineering-insights/add-integration-cio-dashboard.png rename to en/pe-docs/docs/assets/img/monitoring-and-insights/engineering-insights/add-integration-cio-dashboard.png diff --git a/en/site/assets/img/monitoring-and-insights/engineering-insights/add-integration-configure.png b/en/pe-docs/docs/assets/img/monitoring-and-insights/engineering-insights/add-integration-configure.png similarity index 100% rename from en/site/assets/img/monitoring-and-insights/engineering-insights/add-integration-configure.png rename to en/pe-docs/docs/assets/img/monitoring-and-insights/engineering-insights/add-integration-configure.png diff --git a/en/site/assets/img/monitoring-and-insights/engineering-insights/change-failure-rate-chart.png b/en/pe-docs/docs/assets/img/monitoring-and-insights/engineering-insights/change-failure-rate-chart.png similarity index 100% rename from en/site/assets/img/monitoring-and-insights/engineering-insights/change-failure-rate-chart.png rename to en/pe-docs/docs/assets/img/monitoring-and-insights/engineering-insights/change-failure-rate-chart.png diff --git a/en/site/assets/img/monitoring-and-insights/engineering-insights/change-failure-rate-summary.png b/en/pe-docs/docs/assets/img/monitoring-and-insights/engineering-insights/change-failure-rate-summary.png similarity index 100% rename from en/site/assets/img/monitoring-and-insights/engineering-insights/change-failure-rate-summary.png rename to en/pe-docs/docs/assets/img/monitoring-and-insights/engineering-insights/change-failure-rate-summary.png diff --git a/en/pe-docs/docs/assets/img/monitoring-and-insights/engineering-insights/delivery-insights-dashboard.png b/en/pe-docs/docs/assets/img/monitoring-and-insights/engineering-insights/delivery-insights-dashboard.png new file mode 100644 index 000000000..3f5d0208a Binary files /dev/null and b/en/pe-docs/docs/assets/img/monitoring-and-insights/engineering-insights/delivery-insights-dashboard.png differ diff --git a/en/site/assets/img/monitoring-and-insights/engineering-insights/deployment-copy-to-clipboard.png b/en/pe-docs/docs/assets/img/monitoring-and-insights/engineering-insights/deployment-copy-to-clipboard.png similarity index 100% rename from en/site/assets/img/monitoring-and-insights/engineering-insights/deployment-copy-to-clipboard.png rename to en/pe-docs/docs/assets/img/monitoring-and-insights/engineering-insights/deployment-copy-to-clipboard.png diff --git a/en/site/assets/img/monitoring-and-insights/engineering-insights/deployment-frequency-snapshot.png b/en/pe-docs/docs/assets/img/monitoring-and-insights/engineering-insights/deployment-frequency-snapshot.png similarity index 100% rename from en/site/assets/img/monitoring-and-insights/engineering-insights/deployment-frequency-snapshot.png rename to en/pe-docs/docs/assets/img/monitoring-and-insights/engineering-insights/deployment-frequency-snapshot.png diff --git a/en/site/assets/img/monitoring-and-insights/engineering-insights/deployment-frequency-time-series.png b/en/pe-docs/docs/assets/img/monitoring-and-insights/engineering-insights/deployment-frequency-time-series.png similarity index 100% rename from en/site/assets/img/monitoring-and-insights/engineering-insights/deployment-frequency-time-series.png rename to en/pe-docs/docs/assets/img/monitoring-and-insights/engineering-insights/deployment-frequency-time-series.png diff --git a/en/site/assets/img/monitoring-and-insights/engineering-insights/deployment-history.png b/en/pe-docs/docs/assets/img/monitoring-and-insights/engineering-insights/deployment-history.png similarity index 100% rename from en/site/assets/img/monitoring-and-insights/engineering-insights/deployment-history.png rename to en/pe-docs/docs/assets/img/monitoring-and-insights/engineering-insights/deployment-history.png diff --git a/en/site/assets/img/monitoring-and-insights/engineering-insights/dora-matrix.png b/en/pe-docs/docs/assets/img/monitoring-and-insights/engineering-insights/dora-matrix.png similarity index 100% rename from en/site/assets/img/monitoring-and-insights/engineering-insights/dora-matrix.png rename to en/pe-docs/docs/assets/img/monitoring-and-insights/engineering-insights/dora-matrix.png diff --git a/en/site/assets/img/monitoring-and-insights/engineering-insights/dora-metrics-summary.png b/en/pe-docs/docs/assets/img/monitoring-and-insights/engineering-insights/dora-metrics-summary.png similarity index 100% rename from en/site/assets/img/monitoring-and-insights/engineering-insights/dora-metrics-summary.png rename to en/pe-docs/docs/assets/img/monitoring-and-insights/engineering-insights/dora-metrics-summary.png diff --git a/en/pe-docs/docs/assets/img/monitoring-and-insights/engineering-insights/edit-configurations.png b/en/pe-docs/docs/assets/img/monitoring-and-insights/engineering-insights/edit-configurations.png new file mode 100644 index 000000000..1df929271 Binary files /dev/null and b/en/pe-docs/docs/assets/img/monitoring-and-insights/engineering-insights/edit-configurations.png differ diff --git a/en/site/assets/img/monitoring-and-insights/engineering-insights/enable-dora-metrics.png b/en/pe-docs/docs/assets/img/monitoring-and-insights/engineering-insights/enable-dora-metrics.png similarity index 100% rename from en/site/assets/img/monitoring-and-insights/engineering-insights/enable-dora-metrics.png rename to en/pe-docs/docs/assets/img/monitoring-and-insights/engineering-insights/enable-dora-metrics.png diff --git a/en/site/assets/img/monitoring-and-insights/engineering-insights/filter-label.png b/en/pe-docs/docs/assets/img/monitoring-and-insights/engineering-insights/filter-label.png similarity index 100% rename from en/site/assets/img/monitoring-and-insights/engineering-insights/filter-label.png rename to en/pe-docs/docs/assets/img/monitoring-and-insights/engineering-insights/filter-label.png diff --git a/en/site/assets/img/monitoring-and-insights/engineering-insights/lead-time-for-a-change-chart.png b/en/pe-docs/docs/assets/img/monitoring-and-insights/engineering-insights/lead-time-for-a-change-chart.png similarity index 100% rename from en/site/assets/img/monitoring-and-insights/engineering-insights/lead-time-for-a-change-chart.png rename to en/pe-docs/docs/assets/img/monitoring-and-insights/engineering-insights/lead-time-for-a-change-chart.png diff --git a/en/site/assets/img/monitoring-and-insights/engineering-insights/lead-time-for-a-change-summary.png b/en/pe-docs/docs/assets/img/monitoring-and-insights/engineering-insights/lead-time-for-a-change-summary.png similarity index 100% rename from en/site/assets/img/monitoring-and-insights/engineering-insights/lead-time-for-a-change-summary.png rename to en/pe-docs/docs/assets/img/monitoring-and-insights/engineering-insights/lead-time-for-a-change-summary.png diff --git a/en/site/assets/img/monitoring-and-insights/engineering-insights/mean-time-to-recovery-chart.png b/en/pe-docs/docs/assets/img/monitoring-and-insights/engineering-insights/mean-time-to-recovery-chart.png similarity index 100% rename from en/site/assets/img/monitoring-and-insights/engineering-insights/mean-time-to-recovery-chart.png rename to en/pe-docs/docs/assets/img/monitoring-and-insights/engineering-insights/mean-time-to-recovery-chart.png diff --git a/en/site/assets/img/monitoring-and-insights/engineering-insights/mean-time-to-recovery-summary.png b/en/pe-docs/docs/assets/img/monitoring-and-insights/engineering-insights/mean-time-to-recovery-summary.png similarity index 100% rename from en/site/assets/img/monitoring-and-insights/engineering-insights/mean-time-to-recovery-summary.png rename to en/pe-docs/docs/assets/img/monitoring-and-insights/engineering-insights/mean-time-to-recovery-summary.png diff --git a/en/site/assets/img/monitoring-and-insights/engineering-insights/time-series-view.jpg b/en/pe-docs/docs/assets/img/monitoring-and-insights/engineering-insights/time-series-view.jpg similarity index 100% rename from en/site/assets/img/monitoring-and-insights/engineering-insights/time-series-view.jpg rename to en/pe-docs/docs/assets/img/monitoring-and-insights/engineering-insights/time-series-view.jpg diff --git a/en/site/assets/img/monitoring-and-insights/first_time_key_moesif.png b/en/pe-docs/docs/assets/img/monitoring-and-insights/first_time_key_moesif.png similarity index 100% rename from en/site/assets/img/monitoring-and-insights/first_time_key_moesif.png rename to en/pe-docs/docs/assets/img/monitoring-and-insights/first_time_key_moesif.png diff --git a/en/site/assets/img/monitoring-and-insights/observability/diagnostic-view.png b/en/pe-docs/docs/assets/img/monitoring-and-insights/observability/diagnostic-view.png similarity index 100% rename from en/site/assets/img/monitoring-and-insights/observability/diagnostic-view.png rename to en/pe-docs/docs/assets/img/monitoring-and-insights/observability/diagnostic-view.png diff --git a/en/site/assets/img/monitoring-and-insights/observability/logs-panel.png b/en/pe-docs/docs/assets/img/monitoring-and-insights/observability/logs-panel.png similarity index 100% rename from en/site/assets/img/monitoring-and-insights/observability/logs-panel.png rename to en/pe-docs/docs/assets/img/monitoring-and-insights/observability/logs-panel.png diff --git a/en/site/assets/img/monitoring-and-insights/observability/logs.png b/en/pe-docs/docs/assets/img/monitoring-and-insights/observability/logs.png similarity index 100% rename from en/site/assets/img/monitoring-and-insights/observability/logs.png rename to en/pe-docs/docs/assets/img/monitoring-and-insights/observability/logs.png diff --git a/en/site/assets/img/monitoring-and-insights/observability/overview-overall.png b/en/pe-docs/docs/assets/img/monitoring-and-insights/observability/overview-overall.png similarity index 100% rename from en/site/assets/img/monitoring-and-insights/observability/overview-overall.png rename to en/pe-docs/docs/assets/img/monitoring-and-insights/observability/overview-overall.png diff --git a/en/site/assets/img/monitoring-and-insights/observability/throughput-and-latency.png b/en/pe-docs/docs/assets/img/monitoring-and-insights/observability/throughput-and-latency.png similarity index 100% rename from en/site/assets/img/monitoring-and-insights/observability/throughput-and-latency.png rename to en/pe-docs/docs/assets/img/monitoring-and-insights/observability/throughput-and-latency.png diff --git a/en/site/assets/img/monitoring-and-insights/observability/view-application-logs.png b/en/pe-docs/docs/assets/img/monitoring-and-insights/observability/view-application-logs.png similarity index 100% rename from en/site/assets/img/monitoring-and-insights/observability/view-application-logs.png rename to en/pe-docs/docs/assets/img/monitoring-and-insights/observability/view-application-logs.png diff --git a/en/pe-docs/docs/assets/img/monitoring-and-insights/view-logs/audit-logs.png b/en/pe-docs/docs/assets/img/monitoring-and-insights/view-logs/audit-logs.png new file mode 100644 index 000000000..3074a53df Binary files /dev/null and b/en/pe-docs/docs/assets/img/monitoring-and-insights/view-logs/audit-logs.png differ diff --git a/en/pe-docs/docs/assets/img/monitoring-and-insights/view-logs/runtime-logs.png b/en/pe-docs/docs/assets/img/monitoring-and-insights/view-logs/runtime-logs.png new file mode 100644 index 000000000..118b6f0fa Binary files /dev/null and b/en/pe-docs/docs/assets/img/monitoring-and-insights/view-logs/runtime-logs.png differ diff --git a/en/site/assets/img/monitoring-and-insights/work-with-choreo-insights-api/create-an-application.png b/en/pe-docs/docs/assets/img/monitoring-and-insights/work-with-choreo-insights-api/create-an-application.png similarity index 100% rename from en/site/assets/img/monitoring-and-insights/work-with-choreo-insights-api/create-an-application.png rename to en/pe-docs/docs/assets/img/monitoring-and-insights/work-with-choreo-insights-api/create-an-application.png diff --git a/en/site/assets/img/monitoring-and-insights/work-with-choreo-insights-api/create-application.png b/en/pe-docs/docs/assets/img/monitoring-and-insights/work-with-choreo-insights-api/create-application.png similarity index 100% rename from en/site/assets/img/monitoring-and-insights/work-with-choreo-insights-api/create-application.png rename to en/pe-docs/docs/assets/img/monitoring-and-insights/work-with-choreo-insights-api/create-application.png diff --git a/en/site/assets/img/monitoring-and-insights/work-with-choreo-insights-api/endpoints.png b/en/pe-docs/docs/assets/img/monitoring-and-insights/work-with-choreo-insights-api/endpoints.png similarity index 100% rename from en/site/assets/img/monitoring-and-insights/work-with-choreo-insights-api/endpoints.png rename to en/pe-docs/docs/assets/img/monitoring-and-insights/work-with-choreo-insights-api/endpoints.png diff --git a/en/site/assets/img/monitoring-and-insights/work-with-choreo-insights-api/generate-credentials.png b/en/pe-docs/docs/assets/img/monitoring-and-insights/work-with-choreo-insights-api/generate-credentials.png similarity index 100% rename from en/site/assets/img/monitoring-and-insights/work-with-choreo-insights-api/generate-credentials.png rename to en/pe-docs/docs/assets/img/monitoring-and-insights/work-with-choreo-insights-api/generate-credentials.png diff --git a/en/site/assets/img/monitoring-and-insights/work-with-choreo-insights-api/request-access.png b/en/pe-docs/docs/assets/img/monitoring-and-insights/work-with-choreo-insights-api/request-access.png similarity index 100% rename from en/site/assets/img/monitoring-and-insights/work-with-choreo-insights-api/request-access.png rename to en/pe-docs/docs/assets/img/monitoring-and-insights/work-with-choreo-insights-api/request-access.png diff --git a/en/site/assets/img/monitoring-and-insights/work-with-choreo-insights-api/subscribe-to-insights-api.png b/en/pe-docs/docs/assets/img/monitoring-and-insights/work-with-choreo-insights-api/subscribe-to-insights-api.png similarity index 100% rename from en/site/assets/img/monitoring-and-insights/work-with-choreo-insights-api/subscribe-to-insights-api.png rename to en/pe-docs/docs/assets/img/monitoring-and-insights/work-with-choreo-insights-api/subscribe-to-insights-api.png diff --git a/en/site/assets/img/monitoring-and-insights/work-with-choreo-insights-api/update-token-expirary-time.png b/en/pe-docs/docs/assets/img/monitoring-and-insights/work-with-choreo-insights-api/update-token-expirary-time.png similarity index 100% rename from en/site/assets/img/monitoring-and-insights/work-with-choreo-insights-api/update-token-expirary-time.png rename to en/pe-docs/docs/assets/img/monitoring-and-insights/work-with-choreo-insights-api/update-token-expirary-time.png diff --git a/en/pe-docs/docs/assets/img/platform-services/kafka-service-overview.png b/en/pe-docs/docs/assets/img/platform-services/kafka-service-overview.png new file mode 100644 index 000000000..11e178b6e Binary files /dev/null and b/en/pe-docs/docs/assets/img/platform-services/kafka-service-overview.png differ diff --git a/en/pe-docs/docs/assets/img/platform-services/set-ca-certificate.png b/en/pe-docs/docs/assets/img/platform-services/set-ca-certificate.png new file mode 100644 index 000000000..1fd3be8dd Binary files /dev/null and b/en/pe-docs/docs/assets/img/platform-services/set-ca-certificate.png differ diff --git a/en/pe-docs/docs/assets/img/platform-services/set-environment-variables.png b/en/pe-docs/docs/assets/img/platform-services/set-environment-variables.png new file mode 100644 index 000000000..91ce81f3d Binary files /dev/null and b/en/pe-docs/docs/assets/img/platform-services/set-environment-variables.png differ diff --git a/en/site/assets/img/quick-start-guides/api-proxy-response.png b/en/pe-docs/docs/assets/img/quick-start-guides/api-proxy-response.png similarity index 100% rename from en/site/assets/img/quick-start-guides/api-proxy-response.png rename to en/pe-docs/docs/assets/img/quick-start-guides/api-proxy-response.png diff --git a/en/site/assets/img/quick-start-guides/create-choreo-organization.png b/en/pe-docs/docs/assets/img/quick-start-guides/create-choreo-organization.png similarity index 100% rename from en/site/assets/img/quick-start-guides/create-choreo-organization.png rename to en/pe-docs/docs/assets/img/quick-start-guides/create-choreo-organization.png diff --git a/en/site/assets/img/quick-start-guides/front-end-application.png b/en/pe-docs/docs/assets/img/quick-start-guides/front-end-application.png similarity index 100% rename from en/site/assets/img/quick-start-guides/front-end-application.png rename to en/pe-docs/docs/assets/img/quick-start-guides/front-end-application.png diff --git a/en/site/assets/img/quick-start-guides/web-application.png b/en/pe-docs/docs/assets/img/quick-start-guides/web-application.png similarity index 100% rename from en/site/assets/img/quick-start-guides/web-application.png rename to en/pe-docs/docs/assets/img/quick-start-guides/web-application.png diff --git a/en/site/assets/img/testing/graphql-console-org.png b/en/pe-docs/docs/assets/img/testing/graphql-console-org.png similarity index 100% rename from en/site/assets/img/testing/graphql-console-org.png rename to en/pe-docs/docs/assets/img/testing/graphql-console-org.png diff --git a/en/site/assets/img/testing/graphql-console.png b/en/pe-docs/docs/assets/img/testing/graphql-console.png similarity index 100% rename from en/site/assets/img/testing/graphql-console.png rename to en/pe-docs/docs/assets/img/testing/graphql-console.png diff --git a/en/site/assets/img/testing/openapi-console-org.png b/en/pe-docs/docs/assets/img/testing/openapi-console-org.png similarity index 100% rename from en/site/assets/img/testing/openapi-console-org.png rename to en/pe-docs/docs/assets/img/testing/openapi-console-org.png diff --git a/en/site/assets/img/testing/openapi-console.png b/en/pe-docs/docs/assets/img/testing/openapi-console.png similarity index 100% rename from en/site/assets/img/testing/openapi-console.png rename to en/pe-docs/docs/assets/img/testing/openapi-console.png diff --git a/en/pe-docs/docs/assets/img/testing/websocket-console.png b/en/pe-docs/docs/assets/img/testing/websocket-console.png new file mode 100644 index 000000000..c7814c1d9 Binary files /dev/null and b/en/pe-docs/docs/assets/img/testing/websocket-console.png differ diff --git a/en/site/assets/img/tutorials/api-proxy-response.png b/en/pe-docs/docs/assets/img/tutorials/api-proxy-response.png similarity index 100% rename from en/site/assets/img/tutorials/api-proxy-response.png rename to en/pe-docs/docs/assets/img/tutorials/api-proxy-response.png diff --git a/en/site/assets/img/tutorials/role-based-auth/access-token.png b/en/pe-docs/docs/assets/img/tutorials/role-based-auth/access-token.png similarity index 100% rename from en/site/assets/img/tutorials/role-based-auth/access-token.png rename to en/pe-docs/docs/assets/img/tutorials/role-based-auth/access-token.png diff --git a/en/site/assets/img/tutorials/role-based-auth/api-resources.png b/en/pe-docs/docs/assets/img/tutorials/role-based-auth/api-resources.png similarity index 100% rename from en/site/assets/img/tutorials/role-based-auth/api-resources.png rename to en/pe-docs/docs/assets/img/tutorials/role-based-auth/api-resources.png diff --git a/en/site/assets/img/tutorials/role-based-auth/authorize-endpoint.png b/en/pe-docs/docs/assets/img/tutorials/role-based-auth/authorize-endpoint.png similarity index 100% rename from en/site/assets/img/tutorials/role-based-auth/authorize-endpoint.png rename to en/pe-docs/docs/assets/img/tutorials/role-based-auth/authorize-endpoint.png diff --git a/en/site/assets/img/tutorials/role-based-auth/callback-url.png b/en/pe-docs/docs/assets/img/tutorials/role-based-auth/callback-url.png similarity index 100% rename from en/site/assets/img/tutorials/role-based-auth/callback-url.png rename to en/pe-docs/docs/assets/img/tutorials/role-based-auth/callback-url.png diff --git a/en/site/assets/img/tutorials/role-based-auth/code.png b/en/pe-docs/docs/assets/img/tutorials/role-based-auth/code.png similarity index 100% rename from en/site/assets/img/tutorials/role-based-auth/code.png rename to en/pe-docs/docs/assets/img/tutorials/role-based-auth/code.png diff --git a/en/site/assets/img/tutorials/role-based-auth/consent.png b/en/pe-docs/docs/assets/img/tutorials/role-based-auth/consent.png similarity index 100% rename from en/site/assets/img/tutorials/role-based-auth/consent.png rename to en/pe-docs/docs/assets/img/tutorials/role-based-auth/consent.png diff --git a/en/site/assets/img/tutorials/role-based-auth/consumer-key.png b/en/pe-docs/docs/assets/img/tutorials/role-based-auth/consumer-key.png similarity index 100% rename from en/site/assets/img/tutorials/role-based-auth/consumer-key.png rename to en/pe-docs/docs/assets/img/tutorials/role-based-auth/consumer-key.png diff --git a/en/site/assets/img/tutorials/role-based-auth/enable-asgardeo-key-manager.png b/en/pe-docs/docs/assets/img/tutorials/role-based-auth/enable-asgardeo-key-manager.png similarity index 100% rename from en/site/assets/img/tutorials/role-based-auth/enable-asgardeo-key-manager.png rename to en/pe-docs/docs/assets/img/tutorials/role-based-auth/enable-asgardeo-key-manager.png diff --git a/en/site/assets/img/tutorials/role-based-auth/manage-permission.png b/en/pe-docs/docs/assets/img/tutorials/role-based-auth/manage-permission.png similarity index 100% rename from en/site/assets/img/tutorials/role-based-auth/manage-permission.png rename to en/pe-docs/docs/assets/img/tutorials/role-based-auth/manage-permission.png diff --git a/en/site/assets/img/tutorials/role-based-auth/permission-values.png b/en/pe-docs/docs/assets/img/tutorials/role-based-auth/permission-values.png similarity index 100% rename from en/site/assets/img/tutorials/role-based-auth/permission-values.png rename to en/pe-docs/docs/assets/img/tutorials/role-based-auth/permission-values.png diff --git a/en/site/assets/img/tutorials/role-based-auth/resource-permission.png b/en/pe-docs/docs/assets/img/tutorials/role-based-auth/resource-permission.png similarity index 100% rename from en/site/assets/img/tutorials/role-based-auth/resource-permission.png rename to en/pe-docs/docs/assets/img/tutorials/role-based-auth/resource-permission.png diff --git a/en/site/assets/img/tutorials/role-based-auth/scope-validation-failed.png b/en/pe-docs/docs/assets/img/tutorials/role-based-auth/scope-validation-failed.png similarity index 100% rename from en/site/assets/img/tutorials/role-based-auth/scope-validation-failed.png rename to en/pe-docs/docs/assets/img/tutorials/role-based-auth/scope-validation-failed.png diff --git a/en/site/assets/img/tutorials/role-based-auth/scopes.png b/en/pe-docs/docs/assets/img/tutorials/role-based-auth/scopes.png similarity index 100% rename from en/site/assets/img/tutorials/role-based-auth/scopes.png rename to en/pe-docs/docs/assets/img/tutorials/role-based-auth/scopes.png diff --git a/en/site/assets/img/tutorials/role-based-auth/sign-in-kim.png b/en/pe-docs/docs/assets/img/tutorials/role-based-auth/sign-in-kim.png similarity index 100% rename from en/site/assets/img/tutorials/role-based-auth/sign-in-kim.png rename to en/pe-docs/docs/assets/img/tutorials/role-based-auth/sign-in-kim.png diff --git a/en/site/assets/img/tutorials/role-based-auth/sign-in.png b/en/pe-docs/docs/assets/img/tutorials/role-based-auth/sign-in.png similarity index 100% rename from en/site/assets/img/tutorials/role-based-auth/sign-in.png rename to en/pe-docs/docs/assets/img/tutorials/role-based-auth/sign-in.png diff --git a/en/site/assets/img/tutorials/role-based-auth/token-endpoint.png b/en/pe-docs/docs/assets/img/tutorials/role-based-auth/token-endpoint.png similarity index 100% rename from en/site/assets/img/tutorials/role-based-auth/token-endpoint.png rename to en/pe-docs/docs/assets/img/tutorials/role-based-auth/token-endpoint.png diff --git a/en/site/assets/js/choreotheme.js b/en/pe-docs/docs/assets/js/choreotheme.js similarity index 100% rename from en/site/assets/js/choreotheme.js rename to en/pe-docs/docs/assets/js/choreotheme.js diff --git a/en/site/assets/js/prism-ballerina.js b/en/pe-docs/docs/assets/js/prism-ballerina.js similarity index 100% rename from en/site/assets/js/prism-ballerina.js rename to en/pe-docs/docs/assets/js/prism-ballerina.js diff --git a/en/site/assets/js/theme.js b/en/pe-docs/docs/assets/js/theme.js similarity index 100% rename from en/site/assets/js/theme.js rename to en/pe-docs/docs/assets/js/theme.js diff --git a/en/site/assets/lib/backtotop/img/cd-top-arrow.svg b/en/pe-docs/docs/assets/lib/backtotop/img/cd-top-arrow.svg old mode 100644 new mode 100755 similarity index 100% rename from en/site/assets/lib/backtotop/img/cd-top-arrow.svg rename to en/pe-docs/docs/assets/lib/backtotop/img/cd-top-arrow.svg diff --git a/en/site/assets/lib/backtotop/js/main.js b/en/pe-docs/docs/assets/lib/backtotop/js/main.js old mode 100644 new mode 100755 similarity index 100% rename from en/site/assets/lib/backtotop/js/main.js rename to en/pe-docs/docs/assets/lib/backtotop/js/main.js diff --git a/en/site/assets/lib/backtotop/js/util.js b/en/pe-docs/docs/assets/lib/backtotop/js/util.js old mode 100644 new mode 100755 similarity index 100% rename from en/site/assets/lib/backtotop/js/util.js rename to en/pe-docs/docs/assets/lib/backtotop/js/util.js diff --git a/en/site/assets/lib/highlightjs/ballerina.min.js b/en/pe-docs/docs/assets/lib/highlightjs/ballerina.min.js similarity index 100% rename from en/site/assets/lib/highlightjs/ballerina.min.js rename to en/pe-docs/docs/assets/lib/highlightjs/ballerina.min.js diff --git a/en/site/assets/lib/highlightjs/default.min.css b/en/pe-docs/docs/assets/lib/highlightjs/default.min.css similarity index 100% rename from en/site/assets/lib/highlightjs/default.min.css rename to en/pe-docs/docs/assets/lib/highlightjs/default.min.css diff --git a/en/site/assets/lib/highlightjs/highlight.min.js b/en/pe-docs/docs/assets/lib/highlightjs/highlight.min.js similarity index 100% rename from en/site/assets/lib/highlightjs/highlight.min.js rename to en/pe-docs/docs/assets/lib/highlightjs/highlight.min.js diff --git a/en/site/assets/lib/json-formatter/json-formatter.css b/en/pe-docs/docs/assets/lib/json-formatter/json-formatter.css old mode 100644 new mode 100755 similarity index 100% rename from en/site/assets/lib/json-formatter/json-formatter.css rename to en/pe-docs/docs/assets/lib/json-formatter/json-formatter.css diff --git a/en/site/assets/lib/json-formatter/json-formatter.umd.js b/en/pe-docs/docs/assets/lib/json-formatter/json-formatter.umd.js old mode 100644 new mode 100755 similarity index 100% rename from en/site/assets/lib/json-formatter/json-formatter.umd.js rename to en/pe-docs/docs/assets/lib/json-formatter/json-formatter.umd.js diff --git a/en/site/assets/lib/prism/prism.js b/en/pe-docs/docs/assets/lib/prism/prism.js similarity index 100% rename from en/site/assets/lib/prism/prism.js rename to en/pe-docs/docs/assets/lib/prism/prism.js diff --git a/en/pe-docs/docs/choreo-cli/choreo-cli-overview.md b/en/pe-docs/docs/choreo-cli/choreo-cli-overview.md new file mode 100644 index 000000000..6ec5834d3 --- /dev/null +++ b/en/pe-docs/docs/choreo-cli/choreo-cli-overview.md @@ -0,0 +1,29 @@ +# Choreo Command-Line Interface (CLI) Overview + +The Choreo command-line interface (CLI) is a command-line tool that helps you easily work with Choreo using commands. By utilizing commands, it significantly improves the development experience for Choreo users. This versatile tool simplifies different stages of the development process, making interactions more efficient and user-friendly. + +Choreo serves as a comprehensive internal platform-as-a-service. The Choreo CLI serves as a pivotal tool aimed at enhancing its capabilities. With the Choreo CLI, you can leverage the following benefits: + +- **Streamline Deployment Processes**: Choreo CLI simplifies the entire process from creating a component in Choreo, building it, to deploying, testing, and monitoring independent of the language and framework used to implement the component. + +- **Versatile workflow across frameworks**: Regardless of your chosen framework, Choreo CLI offers a uniform end-to-end process. Choreo seamlessly integrates with different web application types (SPA, SSR, SSG, or simple static files), services (REST, GraphQL, gRPC), scheduled jobs, manual triggers, API proxies, and more. This versatility enables you to orchestrate a wide range of cloud-native components seamlessly. + +## Key features of the Choreo CLI + +- **Create and Manage Resources**: Simplify project and component management. You can easily initiate and organize projects in Choreo through simple commands. + + - **Create Builds and Deployments**: Simplifies the process of creating builds and deploying components. You can build and promote components to environments easily with simple commands, ensuring a seamless transition from development to deployment. + + !!! info "Note" + + The Choreo CLI currently supports the following component types: + + - Service + - Web Application + - Webhook + - Scheduled Task + - Manual Task + +- **Monitor with Logs** : The integrated log functionality in the Choreo CLI allows you to effectively monitor your components. You can access valuable insights into your components behavior and performance directly from the command line. + +For troubleshooting tips and answers to frequently asked questions, see the [Choreo CLI FAQ](../references/faq.md#choreo-cli). diff --git a/en/pe-docs/docs/choreo-cli/get-started-with-the-choreo-cli.md b/en/pe-docs/docs/choreo-cli/get-started-with-the-choreo-cli.md new file mode 100644 index 000000000..0966dff4f --- /dev/null +++ b/en/pe-docs/docs/choreo-cli/get-started-with-the-choreo-cli.md @@ -0,0 +1,199 @@ +# Get Started with the Choreo CLI + +This guide walks you through the following sample use case: + +- View applications within a project +- Build an application +- Deploy the application in the development environment +- Promote the application to the production environment +- View Runtime logs + +This guide utilized a simple to-do app built with Next.js and two basic environments: Development and Production. + +## Prerequisites + +Follow the steps below to install the CLI: + +1. Install the Choreo CLI by running the command specific to your operating system: + + - For Linux and Mac OS + ``` sh + curl -o- https://cli.choreo.dev/install.sh | bash + ``` + + - For Windows (via PowerShell) + ``` sh + iwr https://cli.choreo.dev/install.ps1 -useb | iex + ``` + +2. Verify the installation by running the following command: + + ``` sh + choreo --version + ``` + +## Step 1: Login to Choreo + +Run the following command to login to Choreo: + +``` bash +choreo login +``` + +!!! note + You can generate a [Personal Access Token (PAT)](./manage-authentication-with-personal-access-tokens.md) and use it instead of interactive login. + +Follow the instructions on the console to open the link in the browser and login to Choreo. + +## Step 2: Create a project + +A project in Choreo is a logical group of related components that typically represent a single cloud-native application. A project consists of one or more components. + +Create a multi-repository project named ‘web-app-project’ by running the following command: + +``` sh +choreo create project web-app-project --type=multi-repository +``` +## Step 3: Create a Web Application component + +!!! info "Note" + + To perform this action, you should have **Create Component** permission under **COMPONENT-MANAGEMENT** permission group. By default, platform engineer role does not have this permission. If you are not supposed to have this permission, you can ask a user who has developer role to create one for you. + +In Choreo, a component within your project represents a singular unit of work in a cloud-native application. It can be a microservice, API, web application, or job/task. Each component is associated with a directory path in a Git repository containing the source code for the program. + +!!! info "Note" + + The Choreo CLI currently supports the following component types: + + - Service + - Web Application + - Webhook + - Scheduled Task + - Manual Task + +1. Fork the repository [https://github.com/wso2/choreo-sample-todo-list-app](https://github.com/wso2/choreo-sample-todo-list-app). This contains a sample web application that you can use for this guide. + +2. To initiate the creation of a Web Application component within your project, use the following command: +This triggers a wizard prompting you to provide details for your Git repository and other configurations for your component. + + ``` sh + choreo create component my-web-app --project=web-app-project --type=webApp + ``` + +3. Select the option `Enter remote repository URL manually`. +4. Enter the following values for the prompts. + + | Prompt | value | + |-----------------------------|----------------------------------------| + | Configure source repository | `Enter remote repository URL manually` | + | Remote repository URL | Your forked repository | + | Branch | `main` | + | Directory | `. ` | + | Build-pack | `nodejs` | + | Language Version | `20.x.x` | + | Port | `8080` | + + !!! note + The prompts may vary based on the type of component and the chosen build pack. + +## Step 4: List Components inside Project + +To list down the components in the project, you can use the following command: + +``` sh +choreo list components --project="web-app-project" +``` + +## Step 5: View component details + +To view comprehensive information about the component, including basic details and service endpoint URLs once the services are deployed, you can use the following command: + +``` sh +choreo describe component "my-web-app" --project="web-app-project" +``` + +## Step 6: Build the component + +You must build the components before deploying them to a specific environment. Execute the following command to trigger the build: + +``` sh +choreo create build "my-web-app" --project="web-app-project" +``` + +To view the builds in Progres: + +```sh +choreo list builds --project="web-app-project" --component="my-web-app" +``` + +### Step 6.1: View build status + +To check the status of a specific build, run the following command, replacing with the actual build ID obtained from the previous command: + +!!! note + Typically, a build takes approximately 2 to 5 minutes to complete. + +``` sh +choreo describe build --project="web-app-project" --component="my-web-app" +``` + +### Step 6.2: View build logs + +Once the build is complete, you can view the build logs for verification or debugging purposes. In the unlikely case, the build encounters any issues, the logs will help you troubleshoot. + +``` sh +choreo logs --type=build --project="web-app-project" --component="my-web-app" --deployment-track="main" --build-id= +``` + +## Step 7: Deploy to the Development environment + +Once the build status indicates `successful` you can deploy the component in the Development environment by running the following command: + +``` sh +choreo create deployment "my-web-app" --env=Development --project="web-app-project" --build-id= +``` + +### Step 7.1: Verify the deployment in the Development environment + +After deploying the component, you can retrieve the URL of the deployed web application and open the publicly available web page to verify its behavior. Use the following command to retrieve the URL: + +``` bash +choreo describe component "my-web-app" --project="web-app-project" +``` + +### Step 7.2: View runtime logs + +To observe runtime application logs of the web application in the Development environment, execute the following command: + +``` sh +choreo logs --type component-application --component my-web-app --project web-app-project --env Development --follow +``` + +## Step 8: Deploy to the Production environment + +Once you verify your application in the Development environment, you can proceed to deploy it to the Production environment with the following command: + +- Be sure to substitute with the id obtained after triggering the build. + +``` sh +choreo create deployment "my-web-app" --env=Production --project="web-app-project" --build-id= +``` + +### Step 8.1: Verify the deployment in the Production environment + +To ensure a successful deployment to the Production environment, retrieve the URL of the deployed web application using the following command: + +``` sh +choreo describe component "my-web-app" --project="web-app-project" +``` + +Congratulations! You successfully deployed your web application in Choreo using the Choreo CLI. + +## View all CLI functions + +Discover other functionalities of Choreo by running the following command. + +``` sh +choreo --help +``` diff --git a/en/pe-docs/docs/choreo-cli/manage-authentication-with-personal-access-tokens.md b/en/pe-docs/docs/choreo-cli/manage-authentication-with-personal-access-tokens.md new file mode 100644 index 000000000..55e70d21e --- /dev/null +++ b/en/pe-docs/docs/choreo-cli/manage-authentication-with-personal-access-tokens.md @@ -0,0 +1,96 @@ +# Manage Authentication with Personal Access Tokens + +Personal access tokens (PATs) provide a secure method to authenticate with the Choreo CLI, allowing you to manage access without relying on primary credentials. + +## What are personal access tokens? + +Personal access tokens are unique strings that provide an alternative to username and password authentication. You can create PATs for specific use cases, associating them with your account to grant granular access to your application resources as needed. + +!!! note + PATs should be treated like passwords and stored securely. + +## Sample use cases for personal access tokens + +PATs are versatile and suitable for various tasks in the Choreo CLI: + +- **Automated scripting**: To use in scripts for CI/CD pipelines or task automation, avoiding repeated sign-in prompts. This simplifies setting up CI/CD pipelines or other automation that rely on the CLI. +- **Granular permissions for specific tasks**: To limit access to certain commands or specific features without providing full access, you can configure PATs with restricted permissions. +- **Temporary access**: To grant temporary access for short-term projects or collaborations, without sharing full credentials. +- **Integration with third-party tools**: To authenticate other tools or services that need access to +your resources, such as analytics tools, monitoring systems, or deployment services. This approach keeps your main +credentials secure while allowing API access. +- **Multiple account management**: If you work with multiple accounts or roles, you can +use separate PATs for each role for easy context switching. + +## Set up personal access tokens + +To create a PAT to use with the Choreo CLI, you must set up and retrieve a token from the Choreo Console. + +Follow these steps to create a PAT for Choreo CLI: + +1. Sign in to the [Choreo Console](https://console.choreo.dev/). +2. Go to the Choreo Console header right corner, click your profile picture, and then click **Account Settings**. + + ![Profile](../assets/img/choreo-cli/personal-access-tokens/profile.png) + +3. Click the **Personal Access Tokens** tab. + + ![Account settings](../assets/img/choreo-cli/personal-access-tokens/account-settings.png) + +4. Click **+ Create New**. +5. Specify a name for your token and define its scopes and permissions. By default, all necessary scopes for CLI functionality are selected. + + ![Create a PAT](../assets/img/choreo-cli/personal-access-tokens/create-a-pat.png) + +6. Click **Generate**. +7. Copy and securely store the displayed token. You won’t be able to view it again. +8. Click **Done**. + +!!! info "Caution" + - Treat the token as confidential information. + - Avoid storing the token in unprotected files. + +## Use a personal access token with the Choreo CLI + +Once you generate a token, you can use it to authenticate with the Choreo CLI and perform various operations. + +### Command syntax + +To log in with the token, use the following command: + +```bash +choreo login --with-token +``` + +This command reads the token from the standard input. + +**Example:** + +```bash +export CHOREO_TOKEN= +echo "$CHOREO_TOKEN" | choreo login --with-token +``` + +!!! note + Replace `YOUR_PERSONAL_ACCESS_TOKEN` with your actual token. + +## Manage and revoke tokens + +To manage or revoke existing tokens, follow these steps: + +1. Sign in to the [Choreo Console](https://console.choreo.dev/). +2. Go to the Choreo Console header right corner, click your profile picture, and then click **Account Settings**. +3. On the **Account settings** page, click the **Personal Access Tokens** tab. +4. Go to the token you want to revoke and click **Revoke**. + +!!! tip + To maintain security, you must regularly review and revoke tokens that are no longer in use. + +![PAT listing](../assets/img/choreo-cli/personal-access-tokens/pat-listing.png) + +## Best practices for token management + +- **Limit scope:** Assign only the necessary permissions to each token. +- **Rotate tokens regularly:** Replace tokens periodically to enhance security. +- **Use secure storage:**  Store tokens in a secure location, such as a secrets manager. +- **Revoke unused tokens:** Regularly audit and revoke inactive tokens. diff --git a/en/pe-docs/docs/choreo-concepts/choreo-marketplace.md b/en/pe-docs/docs/choreo-concepts/choreo-marketplace.md new file mode 100644 index 000000000..d6c1891b7 --- /dev/null +++ b/en/pe-docs/docs/choreo-concepts/choreo-marketplace.md @@ -0,0 +1,73 @@ +# Choreo Marketplace + +The Choreo Marketplace promotes and facilitates reusing and sharing services. It allows you to share all the services deployed in Choreo. +You can easily browse and search available services within the Marketplace and refer to the service definitions, documentation, instructions on how you can use it, etc. + +![Internal Marketplace](../assets/img/choreo-concepts/marketplace/internal-marketplace.png){.cInlineImage-full} + +## Discover services + +The Marketplace includes all services deployed in your organization. This may be a large number of services. Therefore, effective discoverability is desirable. + +You can use the search or apply various filter criteria to explore the services available. + +### Search + +The top search bar provides universal searching to find the services. It allows you to search for a text in the following search attributes: + +- **Name**: The service name. +- **Label**: The service labels. +- **Content**: The service content: overview, summary, and documentation. +- **All**: All of the above criteria. + +### Filter + +The Choreo Marketplace provides a filtering capability through the left-hand side filter panel. It allows you to filter with the following filter attributes: + +- **Type**: This filter enables you to categorize services based on their type, with two available options: "Internal" and "Third-party". "Internal" refers to services deployed within Choreo, while "Third-party" refers to services running externally to Choreo, independently added to the Marketplace. + +- **Network Visibility**: This filter enables you to categorize services based on their network visibility level, with three choices: "Public," "Organization," and "Project". "Public" filters services exposed publicly, "Organization" represents services exposed across the entire organization, and "Project" represents services exposed at the project level. + +## Explore a service + +You can click on the service card to open the detailed view of the service. The detailed service page features the service name, summary, version, labels, and service icon as the header. + +Choreo organizes the service content into four tabs. The four tabs contain information as follows: + +- **Overview**: Choreo displays the service overview provided by the service developer. If the service developer has not provided any content at service creation, this section will be disabled. The service developer can provide the overview content via the Manage → Marketplace section of the component. + +- **API definition**: Includes the API definition for the service, extracted from the `component.yaml` file in the user repository. If an API definition is not provided, this tab will be empty. + +- **How to use**: Includes instructions on how to use the selected service. + +- **Related documents**: Includes any additional content the user has provided as documents through the Manage -> Marketplace section of the component. + +## Add a service to the Choreo Marketplace + +You can add services to the Marketplace as Choreo services as follows: + +### Add a Choreo service + +In Choreo, a service exposed through the platform is termed a Choreo service, with each service being identifiable by an endpoint within a Choreo service component. The Marketplace showcases a service for each endpoint within a service component. + +Upon deployment to the initial environment, services get automatically added to the Marketplace. Choreo effortlessly collects essential details such as component name, endpoint name, description, and service definitions during this deployment, utilizing them to generate the corresponding service entries in the Marketplace. + +The service name follows the convention of `component name - endpoint name`, while all other details remain unchanged. + +## Service versioning in the Choreo Marketplace + +In the Choreo Marketplace, service versions are displayed in their major version format. Each service in the Choreo Marketplace represents the latest version of the service within its major version, following semantic versioning principles. + +For example, if a Choreo service has versions `v1.0`, `v1.1`, `v1.2`, and `v2.0`, the Choreo Marketplace displays services with versions `v1` and `v2` representing the latest versions `v1.2` and `v2.0` respectively. + +When you deploy a new minor version of a service already deployed in Choreo, the corresponding service in the marketplace automatically updates to reflect the latest version within the same major version. + +### Semantic-version-based intelligent routing in the Choreo Marketplace + +When you use a service from the Choreo marketplace as a dependency, the dependent service's traffic automatically routes to the latest version of the corresponding service within the same major version. This ensures that your dependencies remain up-to-date without requiring manual updates within a major version. + +For example, if you create a connection to connect your Choreo component named `Foo` to a Choreo service named `Bar`, which is currently available in the Choreo Marketplace as version v1, and if the latest version of the service `Bar` within the v1 range is v1.2, the component `Foo` will automatically connect to `Bar` v1.2. Subsequently, when `Bar` releases version v1.3, traffic from `Foo` will automatically route to `Bar` v1.3. + +## Edit services in the Choreo Marketplace + +You can edit services in the Choreo Marketplace. During redeployment to any environment, Choreo automatically updates service definitions, visibility, and descriptions. diff --git a/en/pe-docs/docs/choreo-concepts/ci-cd.md b/en/pe-docs/docs/choreo-concepts/ci-cd.md new file mode 100644 index 000000000..790b98898 --- /dev/null +++ b/en/pe-docs/docs/choreo-concepts/ci-cd.md @@ -0,0 +1,90 @@ +# CI/CD + +Choreo provides a streamlined continuous integration and continuous deployment (CI/CD) experience to deploy applications and services efficiently across multiple environments. + +Choreo creates environments for each project, where all components within the project share the environments. An environment is an isolated deployment area with restricted network and resource access. Services deployed in one environment cannot communicate with services deployed in another. + +The Choreo cloud data plane provides two default environments (i.e., development and production). However, if you are in a private data plane organization, you can customize and create multiple environments based on your requirements. + +Choreo adopts a *build once, deploy many* strategy to manage components across multiple environments. An application is built only once (i.e., per commit if automatic build on commit is enabled or based on the selected commit during a manual build). Then it is promoted to subsequent environments. This allows testing changes in lower, non-production environments like development before promoting the build to production. + +Choreo injects configurations and secrets that you maintain at the environment level into components at runtime. This ensures a strict separation of environment-specific configurations from source code. Although configurations can vary across environments, the code and the built container remain unchanged. Configurations and secrets include: + +- Resource credentials to a database, cache, or other backing services. +- Credentials to external cloud services such as Amazon S3 or external APIs. + +All configurations and secrets are encrypted at rest and in transit and stored in a secure vault. In a private data plane organization, you can store configurations and secrets in your infrastructure. + +## Continuous Integration + +Choreo auto-generates build pipelines that may slightly differ depending on the component type you create. Generally, all build pipelines work as follows: + +- Builds a container image either from the provided source code or from a given Dockerfile for a specific commit. +- Runs security and vulnerability scans if applicable, depending on the component type. +- Pushes the container image to a container registry. In the cloud data plane, Choreo pushes the image to a Choreo-managed registry. If it is a private data plane organization, Choreo pushes the image to a registry that you own. +- Updates service endpoints and API specifications from the provided repository if applicable. + +With Auto Build on Commit, you can configure the build pipeline to be triggered once a new commit is available in the repository's selected branch without any user intervention. + +In addition to these steps, some buildpacks support integrating unit tests into the build pipeline. For more details, see [Integrate Unit Tests into the Choreo CI Pipeline](../devops/ci-pipelines/integrate-unit-tests-into-the-build-pipeline.md). + +## Continuos Deployment + +Once you build an image in Choreo, you can deploy it via the **CD Pipelines** page. To deploy an image, you can follow one of the approaches given below: + +- **Manually deploy**: In the **CD Pipelines** page, go to the **Set Up** card and click **Deploy**. +- **Automatically deploy on build**: In the **CD Pipelines** page, go to the **Set Up** card and enable **Auto Deploy on Build**. This automatically initiates deployment upon the completion of an automatic build. + +!!! info + To enable **Auto Deploy on Build**, you must enable **Auto Build on Commit**. This is because automatic deployment is not necessary or useful in scenarios where automatic build is not enabled. + +!!! note + - You must trigger the first build in a Ballerina component manually to ensure that Choreo applies the required configurations to the development environment. You can enable automatic builds subsequently. + - Choreo automatically checks the configurable defined in your source code against the configurable values applied in an environment. Choreo requests the configurable values on deployment and promotion. If you have changed the configurables in your Ballerina component, auto-build pipelines can fail as a precaution to avoid a component crash at runtime due to missing configurables. + - The configurable verifying capability is only available for Ballerina components. For Dockerfile-based components, ensure to manage and update the configurations and secrets in environments ahead of time. You must also ensure backward compatibility between at least one release if you change the configurations. + +### Set up area and initial deployment + +In the deploy phase, Choreo uses a setup area to merge the Docker image with its environment-independent configurations. Choreo then deploys this composite to the environment. This is known as the initial deployment. + +### Immutable deployments + +Once Choreo deploys a component with configurations, the configurations become immutable. Any subsequent change results in a new deployment. + +### Promote a component to a higher environment + +You can go to the **CD Pipelines** page of a component and promote it manually across environments. + +## Configurations + +Choreo allows you to define both environment-independent configurations and environment-specific configurations. + +### Environment-independent configurations + +These configurations apply to all environments. + +To change environment-independent configurations, go to the **CD Pipelines** page of the component, make the necessary configuration changes via the **Set Up** card, and then trigger a new deployment to the initial environment. From there, you can proceed to promote the component to higher environments. + +### Environment-specific configurations + +These configurations apply to a particular environment. + +To change environment-specific configurations, go to the **CD Pipelines** page of the component, make the necessary configuration changes via the specific environment card, and trigger a new deployment. + +To learn more about managing these configurations, see [Configuration Management](https://wso2.com/choreo/docs/choreo-concepts/configuration-management/). + +## Task execution + +The information on the **Execute** page is only applicable to scheduled and manual task components. + +To track and monitor executions associated with a deployed scheduled task or manual task, go to the left navigation menu and click **Execute**. + +You can view current and historic execution details along with a quick snapshot of recent activity via the total count of executions within the last 30 days. For each execution, you can view vital details such as the unique execution ID, the time it was triggered, and relevant revision information. Furthermore, you can dive deeper into the details by clicking on a specific execution to access its associated logs. This information enhances transparency, troubleshooting capabilities, and overall execution management, allowing you to easily monitor and analyze workflows. + +## Zero-downtime deployments + +Choreo performs rolling updates to ensure zero downtime between deployments and promotions. + +A new build undergoes a health check before traffic is switched to it from the current build. + +If you configure the necessary health checks for a component, it can prevent deploying and promoting unhealthy versions of a component. diff --git a/en/pe-docs/docs/choreo-concepts/component.md b/en/pe-docs/docs/choreo-concepts/component.md new file mode 100644 index 000000000..027a11f3a --- /dev/null +++ b/en/pe-docs/docs/choreo-concepts/component.md @@ -0,0 +1,6 @@ +# Component + +A component within a project represents a single unit of work in a cloud native application. A component is usually a single microservice, API, or job/task. Each component in Choreo is attached to a given directory path in a Git repository which either contains program source code or a Dockerfile with build instructions. A component is Choreo’s unit of deployment. Each component maps to a single pod in the Kubernetes cluster (data plane) at deployment time. Therefore, you can deploy, manage, and scale each component in Choreo independently. + +Choreo supports different component types for various use cases. These include component types such as services, API proxies, integrations, web applications, and so on. Each component type hosts unique features based on its characteristics. For example, a scheduled integration component can accept a cron expression as a configuration to schedule an integration job/task. + diff --git a/en/pe-docs/docs/choreo-concepts/connections.md b/en/pe-docs/docs/choreo-concepts/connections.md new file mode 100644 index 000000000..7f6cf5a58 --- /dev/null +++ b/en/pe-docs/docs/choreo-concepts/connections.md @@ -0,0 +1,23 @@ +# Connections + +Services can exist in two main forms: standalone and integrated. Connecting services is an integral part in creating integrated solutions. Choreo allows you to connect services using Connections. + +Using Connections, you can integrate the service you intend to deploy on Choreo with other services on Choreo or external resources. Upon creating a connection to a service on Choreo, Choreo provides you a Connection ID along with a set of connection parameters. Thereafter, you have the capability to configure your service to establish a connection using this Connection ID and map connection parameters to environment variable names in your Choreo component. You can read these environment variable names in your service implementation to retrieve the values, to create a programmatic connection to the service you want to consume. + +At runtime, Choreo dynamically injects values into the environment variables based on the configured mapping. This approach ensures that the connection parameter values and the service connection creation remain loosely coupled, providing developers with flexibility and ease of maintenance. + +You can add Connections in different visibility levels: Project and Component. The visibility levels are described below: + +## Project Connections + +Project Connections are Connections you create to connect to services within a particular project. The Connections **can be used by any component within the project**. + +For example, if you want to share a third-party service like Twilio across the project for all the components within that project to reuse, you can create a project connection. Components can refer to Project Connections using the connection ID. +Project connections created to consume Choreo services under the OAuth security scheme will share the same OAuth application across the project. Any component reusing such a connection will use the same client ID and client secret. + +## Component Connections + +Component Connections are Connections you define at the component level and **used by only that component**. + +For example, create a component connection if you want to connect a legacy service to a given component. Components can refer to the Component Connection using the connection ID. +If your component consumes more than one Choreo service, the Component connections created to consume those Choreo services under the OAuth security scheme can share the same OAuth application by sharing the same client ID and secret between all such connections. diff --git a/en/pe-docs/docs/choreo-concepts/data-planes.md b/en/pe-docs/docs/choreo-concepts/data-planes.md new file mode 100644 index 000000000..d23b28de7 --- /dev/null +++ b/en/pe-docs/docs/choreo-concepts/data-planes.md @@ -0,0 +1,152 @@ +# Data Planes + +Choreo's architecture comprises two key components: the control plane and the data plane. The control plane handles essential tasks such as administering organizations, users, and projects. In addition, it also governs the entire journey of application development, from the initial stages of creation, progressing to deployment, including measures to enforce governance and the provision for observability. The Choreo control plane is a SaaS that manages all cloud data planes and private data planes. It caters to diverse user personas, including CIOs, architects, and developers, as well as DevOps, site reliability engineers, and platform engineers. + +The data plane is the environment where user applications are deployed based on configurations set in the control plane. These applications can range from services and web applications to APIs, integrations, and scheduled tasks. The applications can be written in various programming languages, allowing for a polyglot approach. Importantly, all traffic related to the runtime of user applications is restricted to the Choreo data plane, ensuring strict containment of user data within its boundaries. + +Choreo's architecture features two distinct data plane types: cloud data planes and private data planes. A cloud data plane utilizes a multi-tenanted infrastructure model for deploying user applications, creating a shared yet secure environment for application runtime. In contrast, a private data plane(PDP) provides dedicated infrastructure for a single organization to run its user applications. This ensures an added layer of privacy and control for organizations with specific requirements. + +![Choreo high-level view](../assets/img/choreo-concepts/high-level-view.png) + +## Private data planes + +### Infrastructure + +Choreo private data planes can be deployed with almost all major cloud providers, such as Azure, AWS, and GCP, and are also compatible with on-premises infrastructure. + +The essential requirements for a private data plane include upstream-compatible Kubernetes clusters, a container registry, a key vault (secret store), and a logging service or log storage. + +![Private data plane architecture](../assets/img/choreo-concepts/private-data-plane-architecture.png) + +### System components + +Setting up the Choreo PDP system involves using a Helm installation on the Kubernetes infrastructure. +The following software components are installed during the helm execution: + + - Cilium CNI and service mesh. + - Choreo API Gateways and related components. + - Choreo PDP agent. + - Observability and logging APIs, along with observability agents. + - Flux controller. + +All of these software components receive automatic updates, including security patches and bug fixes through the flux controller connected to the Choreo Update Management System. + +### Connectivity with the control plane + +The private data plane requires communication with the Choreo control plane to manage various activities. All these communications are outbound from the private data plane, ensuring that there is no need to open any specific `IP:Port` from its perspective for these interactions. However, if an organization's network restricts all outbound traffic, it is necessary to permit outbound traffic to the public IP range of the Choreo control plane. + +The following table outlines the inbound and outbound connections from a private data plane: + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Data plane componentEndpointDirectionProtocol
Choreo PDP agentChoreo control plane (CP) (mizzen server)OutboundWSS
Kubernetes API serverOutbound (cluster internal)HTTPS, WS
APIM/local adaptorGlobal adaptorOutboundHTTPS
Azure Service Bus (CP)OutboundAMQP or WS
APIM/EnforcerEvent hub (CP)OutboundAMQP
Choreo secret resolverCloud secret storeOutbound (VPC internal)HTTPS
Container registryContainer registry (public)InboundHTTPS
Container registryOutbound (VPC internal)HTTPS
Certificate managerAzure DNS serviceOutboundHTTPS
LetsEncryptOutboundHTTPS
Flux source controllerGitHubOutboundHTTPS
Flux Helm controllerChoreo container registryOutboundHTTPS
+ +All communication between the control plane and the private data plane is secured using TLS. + +### Observability architecture + +The following diagram depicts the architecture overview of Choreo's in-data-plane log and observability in Azure PDP: + +![Observability architecture](../assets/img/choreo-concepts/observability-architecture.png) + +The private data plane observability architecture is centered around a strong commitment to data privacy and compliance. This is achieved through a strategic decision to retain logs and observability data within the data planes itself. Key aspects of this architecture include: + +- **Data storage at source**: Logs and observability data are stored within the data plane itself, enhancing security, simplifying access, and ensuring compliance. +- **Direct browser-to-data-plane interaction**: The Choreo Console in the user's browser directly interacts with APIs in the data plane, reducing potential data routing complexities and ensuring a more secure, direct flow of information. +- **Reduced data exposure points**: Fetching data directly from the data plane's APIs minimizes the number of data transfer points, effectively decreasing the chances of data exposure or interception. +- **Compliance with regulatory standards**: The architecture supports data locality, aligning with global regulatory standards like GDPR and CCPA by keeping data in its original environment. +- **Improved performance and real-time insights**: Direct interaction between the browser and data plane results in faster data retrieval, providing users with immediate insights. +- **User transparency and control**: Users have a clear view of their data's location and access methods, alongside granular control over data access. + +### Security + +The Choreo private data plane ensures extensive, production-grade security, ranging from infrastructure and architecture to zero-trust network security. All incoming traffic is protected by a firewall and must undergo authentication and authorization via the API Gateway. It also provides end-to-end network traffic encryption using Cilium transparent encryption, ensuring efficient data path encryption. + +For details on the private data plane security levels supported in Choreo pricing plans, see [Private Data Plane Security Levels](../references/private-data-plane-security-levels.md). + +### Management models + +Choreo supports the following management models for private data planes (PDPs), fostering collaboration between WSO2 and customers across diverse scenarios: + + - WSO2 fully managed (infrastructure and PDP in WSO2 subscription) model + - WSO2 fully managed (infrastructure and PDP in customer subscription) model + - Customer self-managed (WSO2 provides installation script and updates) model + +To explore each management model in detail so that you can make informed decisions depending on the supported cloud-based operations and security, see [Private Data Plane Management Models](../references/private-data-plane-management-models.md). diff --git a/en/pe-docs/docs/choreo-concepts/deployment-tracks.md b/en/pe-docs/docs/choreo-concepts/deployment-tracks.md new file mode 100644 index 000000000..3c47cfa47 --- /dev/null +++ b/en/pe-docs/docs/choreo-concepts/deployment-tracks.md @@ -0,0 +1,50 @@ +# Deployment Tracks + +Deployment Tracks in Choreo are structured pathways for simplified software component deployment. They act like advanced CI/CD pipelines, ensuring your components reach their destinations seamlessly, whether from source code or prebuilt images. They establish an organized and structured approach that minimizes the chances of errors and challenges that are typically associated with deployment workflows. + +## The significance of Deployment Tracks + +Deployment Tracks offer practical solutions to enhance the API consumer experience by addressing two critical challenges: + +- **Streamlined deployment**: Deployment Tracks serve as well-designed routes for your software components, enhancing the organization and reliability of the deployment process, similar to a well-structured express route. + +- **Efficient API versioning**: Especially beneficial for managed APIs, Deployment Tracks provide a straightforward method for creating API versions that seamlessly interact with previous iterations. This simplified version management benefits both API creators and consumers alike. + +## Streamlined deployments + +For streamlined deployments, Choreo dissects two integral approaches that leverage Deployment Tracks: the comprehensive CI/CD integration and the focused CD-Only strategy. + +### CI/CD with Deployment Tracks + +A deployment track is linked to a particular branch within a GitHub repository. This connection is useful for handling deployments to various environments. On Choreo's Deploy page, you can easily visualize the deployments to specific environments associated with your selected deployment track. Moreover, the deployment track has a functionality that initiates automatic deployments for the linked branch. When activated, merging a pull request (PR) triggers a deployment to the development environment. + +![Deployment tracks - source repo](../assets/img/choreo-concepts/deployment-tracks-source-repo.png){.cInlineImage-half} + +### CD-Only strategy with Deployment Tracks + +If you're inclined to use your own Continuous Integration (CI) systems and want to harness the deployment track as a Continuous Deployment (CD) pipeline, you can seamlessly link deployment tracks to a container registry repository. This configuration empowers users to effortlessly deploy images sourced directly from the linked container registry repository. + +![Deployment tracks - container registry](../assets/img/choreo-concepts/deployment-tracks-container-registry.png){.cInlineImage-half} + + +## Efficient API versioning + +**This section applies to only service components**. When working with service components in Choreo, it is important to have an effective API versioning mechanism. Choreo follows a versioning mechanism based on Semantic Versioning (SemVer) but only includes the major version and minor version with the prefix `v`. + +For example, `v1.2`. + +You can follow the approach given below when you version APIs in Choreo: + + - Increment the major version when you make incompatible API changes. + - Increment the minor version when you add functionality in a backward-compatible manner. + +!!! info "What is Semantic Versioning?" + Semantic Versioning (SemVer) is a specification that defines how to assign and increment version numbers for software products, including APIs. For more information, see [Semantic Versioning specification](https://semver.org/#semantic-versioning-specification-semver). + +One of the primary concerns when dealing with SaaS APIs is to minimize disruption for API consumers while continuously developing and deploying updates. + +In compliance with SemVer, changes that don't introduce breaking or additive modifications to the API are categorized as patch updates. Hover, from the perspective of API consumers, these changes should ideally not disrupt their API clients. Typically, API consumers are most concerned with major API version alterations, but there might be instances where minor version changes are communicated to them. + +Therefore, in the context of deployment tracks, API developers only need to specify the major and minor versions being delivered from a particular deployment track. This information is treated as the API version attribute of a deployment track. If the publisher requires versioning for internal tracking purposes, this can be accomplished in Git through the use of Git tags, on GitHub with GitHub releases, and so forth. + +![Deployment tracks - api versioning](../assets/img/choreo-concepts/deployment-tracks-api-versioning.md.png){.cInlineImage-half} diff --git a/en/pe-docs/docs/choreo-concepts/endpoint.md b/en/pe-docs/docs/choreo-concepts/endpoint.md new file mode 100644 index 000000000..ffd5f0d89 --- /dev/null +++ b/en/pe-docs/docs/choreo-concepts/endpoint.md @@ -0,0 +1,5 @@ +# Endpoint + +An Endpoint is a network-exposed function that resides within a component. In Choreo, service and integration components expose one or more endpoints. Each endpoint in a component can have a service contract (OpenAPI, GraphQL SDL) associated with it. This contract is used to expose the endpoint to consumers. In the absence of a contract, Choreo uses /\* exposed on all HTTP verbs as the default contract to expose the service or the integration. + +Each endpoint exposed in a component is considered a single API. Therefore, Choreo allows you to do API management per endpoint for a given component. For example, you can perform lifecycle management and configure security settings per endpoint in a given component. diff --git a/en/pe-docs/docs/choreo-concepts/environments.md b/en/pe-docs/docs/choreo-concepts/environments.md new file mode 100644 index 000000000..2e3f2a579 --- /dev/null +++ b/en/pe-docs/docs/choreo-concepts/environments.md @@ -0,0 +1,9 @@ +# Environments + +Choreo offers developers one or more environments to run their applications within a given data plane. By default, the Choreo cloud data plane provides two environments (i.e., development and production). Each project in Choreo is associated with one or more environments available in the organization. For example, project A may choose to utilize dev, staging, and production environments, while project B may only use development and production environments. + +You can promote components within a project across available environments. When you promote a component, its configuration values can be overridden with environment-specific values. + +The following diagram illustrates how a component is promoted across environments. + +![Choreo environments](../assets/img/choreo-concepts/choreo-environments.png){.cInlineImage-threeQuarter} diff --git a/en/pe-docs/docs/choreo-concepts/organization.md b/en/pe-docs/docs/choreo-concepts/organization.md new file mode 100644 index 000000000..77cc717ba --- /dev/null +++ b/en/pe-docs/docs/choreo-concepts/organization.md @@ -0,0 +1,62 @@ +# Organization + +An organization in Choreo is a logical grouping of users and user resources. A first-time user must create an organization and be a member of it when signing in to Choreo. Users and resources in an organization cannot access resources in another organization unless an admin of the other organization invites them and adds them as a member of that organization. A user cannot create more than one organization. + +## Switch organizations + +If you are a member of more than one organization, you can switch from one organization to another when necessary. To do this, select the required organization from the **Organization** list in the Choreo Console header. + +{% include "../user-management/users/inviting-members.md" %} + +## Manage user permission + +Choreo manages user permissions with groups and roles. + +### Groups + +A group in Choreo is a collection of users, each with one or more roles assigned to them. Users within a group inherit the permissions associated with the roles assigned to that group. For instance, if a user is added to the `API Publisher` group, they will automatically receive the `API Publisher` role. + +Choreo comes with predefined groups already configured with specific roles, as follows: + +- **API Publisher**: A collection of users who have the API Publisher role. +- **API Subscriber**: A collection of users who have the API Subscriber role. +- **Admin** : A collection of users who have the Admin role. +- **Billing Admin** : A collection of users who have the Billing Admin role. +- **Choreo DevOps** : A collection of users who have the Choreo DevOps role. +- **Choreo Platform Engineer** : A collection of users who have the Choreo Platform Engineer role. +- **Developer** : Users who develop, deploy, and manage cloud native applications at scale. +- **External API Subscriber**: A collection of users who have the External API Subscriber role. + +When creating a new group to invite members, be sure to assign a role to the group to ensure users have the required permissions. + +### Roles + +Choreo roles are defined as follows: + +- **API Publisher**: An API publisher can discover, create, publish, delete, test, and manage an API. +- **API Subscriber**: An API subscriber is a developer in a particular organization. An API subscriber can subscribe to an application, manage subscriptions, manage applications, generate API keys, and manage API keys. +- **Admin**: An administrator is responsible for all administration tasks, including user management, customizing the Developer Portal, managing projects, enabling analytics, managing domains, etc. +- **Billing Admin**: Is responsible for billing administration that includes viewing tiers, creating and viewing organizations, managing invoices, viewing and creating subscriptions, and viewing and creating payment methods. +- **Choreo DevOps**: A Choreo DevOps user is a user with access to the Choreo DevOps portal, enabling them to actively manage, ensure dependable deployment, and monitor components. +- **Choreo Platform Engineer**: A Choreo Platform Engineer is a user who performs tasks focusing on infrastructure, governance, service mesh, and monitoring. +- **Developer** : A user who can develop, deploy, and manage cloud native applications at scale. +- **External API subscriber**: External API subscribers are API consumers who have access only to the API Developer Portal. They can join an organization with the sole purpose of consuming APIs. +- **Environment Manager (Deprecated)**: Manages deployment environments. + +## Organization ID + +The Organization ID serves as a unique identifier for each organization. To get the organization ID, follow the steps below: + +1. Go to [https://console.choreo.dev/](https://console.choreo.dev/) and sign in. This opens the project home page. +2. Click on the **Organization** list on the header and select your organization. +3. In the left navigation, click **User Management** and then click on **Users**. +4. Click **Copy ID**. + +## Organization Handle + +The organization handle is a unique string that directly corresponds to your organization's name. To get the organization handle, follow the steps below: + +1. Go to [https://console.choreo.dev/](https://console.choreo.dev/) and sign in. This opens the project home page. +2. Click on the **Organization** list on the header and select your organization. +3. In the left navigation, click **User Management** and then click on **Users**. +4. Click **Copy Handle**. diff --git a/en/pe-docs/docs/choreo-concepts/project.md b/en/pe-docs/docs/choreo-concepts/project.md new file mode 100644 index 000000000..4f1f6cf9f --- /dev/null +++ b/en/pe-docs/docs/choreo-concepts/project.md @@ -0,0 +1,13 @@ +# Project + +A project in Choreo is a logical group of related components that typically represent a single cloud native application. A project consists of one or more components. All components within a project can ideally be (but is not restricted to) in a single GitHub repository under different paths. This is also known as the monorepo architecture. + +At deployment time, all components within a given project are deployed into a single namespace of the Kubernetes cluster. Components within a project can be exposed to the public internet, internally to the rest of the organization, or privately within the project only. A project in Choreo is represented as a cell with regard to the [Cell-based architecture](https://github.com/wso2/reference-architecture/blob/master/reference-architecture-cell-based.md). The following diagram illustrates a project and how the components within a project are laid out at runtime: + +![Project](../assets/img/choreo-concepts/project.png){.cInlineImage-full} + + + + + + diff --git a/en/pe-docs/docs/choreo-concepts/resource-hierarchy.md b/en/pe-docs/docs/choreo-concepts/resource-hierarchy.md new file mode 100644 index 000000000..b3b535a55 --- /dev/null +++ b/en/pe-docs/docs/choreo-concepts/resource-hierarchy.md @@ -0,0 +1,25 @@ +# Resource Hierarchy + + +The following diagram depicts the high-level resources and their relationships in Choreo. + +![Resource hierarchy](../assets/img/choreo-concepts/resource-hierarchy.png){.cInlineImage-full} + +## Organizations and data planes + +Data planes are connected to the organization and are available for all projects within the organization. When you create an environment in a project, the data plane connected to the organization is linked with an automatically generated Kubernetes namespace. + +## Environments and data planes + +Choreo allows multiple Kubernetes clusters to be associated with an environment. This enables you to build highly resilient and resource-efficient solutions that utilize multiple clusters. Choreo synchronizes your applications and workloads between associated clusters in an environment, allowing you to perform multi-cluster deployment with a single click. + +The following diagram illustrates how multiple clusters associate with different environments: + +![Environments and dataplanes](../assets/img/choreo-concepts/environments-and-dataplanes.png){.cInlineImage-full} + +!!! info "Note" + It is not necessary to use a different cluster per environment. You can create multiple environments on the same cluster. The above diagram is an example of a specific solution. Your application architecture may require a different configuration than what is depicted. + +## Components and environments + +Components belong to a project in Choreo, and environments are provisioned per project. When a component is deployed, it is deployed as a container to the specified environment. Once deployed, you can promote the container image across the environments available in the project. \ No newline at end of file diff --git a/en/pe-docs/docs/db-and-services/databases/add-choreo-managed-databases-and-caches-to-the-marketplace.md b/en/pe-docs/docs/db-and-services/databases/add-choreo-managed-databases-and-caches-to-the-marketplace.md new file mode 100644 index 000000000..ae2bd02e2 --- /dev/null +++ b/en/pe-docs/docs/db-and-services/databases/add-choreo-managed-databases-and-caches-to-the-marketplace.md @@ -0,0 +1,46 @@ +# Add Choreo-Managed Databases and Caches to the Marketplace + +When you create a Choreo-managed database or cache, you can add it to the Marketplace, making it available for consumption through a connection. + +!!! note + To add a Choreo-managed database or cache to the Marketplace, you must import at least one credential for it. + +## Step 1: Import credentials + +To import credentials, you can either use the default super admin credentials or the credentials you create using the super admin credentials. When you create a database or cache server, super admin credentials are generated by default. You can use these super admin credentials to create new user credentials. The steps to create new user credentials depend on the type of database or cache you are using. + +You can use the imported credentials to create a connection. During connection setup, you must select credentials for each database from the list of available credentials. + +To import credentials for a database, follow these steps: + +1. Sign in to the [Choreo Console](https://console.choreo.dev/). +2. Go to the Choreo Console header and select your organization from the **Organization** list. +3. In the left navigation menu, click **DB & Services** and then click **Databases**. +4. Click on a required database to view its details. +5. Click the **Databases** tab. +6. Click to expand the database for which you want to import credentials, then click **Import Credentials**. +7. In the **Import Credentials** dialog, do one of the following depending on your requirements: + + - Select **Use Created Credentials** and specify the following: + - A display name for the credentials. + - The database credentials you created to use when setting up database connections in Choreo. + - The environment where you want to use the credentials. + + The steps to create new user credentials depend on the type of database or cache you are using. In general, you must log in to your database server as the super admin using a command-line interface or a database management tool. Then, create new database users with the required permission levels. + + - Select **Use Super Admin Credentials** and specify the following: + - A display name for the credentials. + - The environment where you want to use the credentials. + +8. Click **Save**. + +!!! tip + Choreo allows you to delete imported credentials to prevent their use when establishing new connections. However, deleting credentials will not affect any existing database connections that are already using them. + +## Step 2: Add the database or cache to the Marketplace + +- On the **Databases** tab, click **+Add to Marketplace** corresponding to the database you want to add. + +Once the database is added to the Marketplace, it can be consumed via a connection. +!!! note + To remove a database or cache that you added to the Marketplace, click the corresponding **Remove from Marketplace**. This action prevents new connections to the removed database, but existing connections remain unaffected. diff --git a/en/pe-docs/docs/db-and-services/databases/choreo-managed-caches.md b/en/pe-docs/docs/db-and-services/databases/choreo-managed-caches.md new file mode 100644 index 000000000..0772c1d20 --- /dev/null +++ b/en/pe-docs/docs/db-and-services/databases/choreo-managed-caches.md @@ -0,0 +1,128 @@ +# Choreo-Managed Cache + +Fully compatible with legacy Redis® OSS. + +Choreo-Managed Cache provides fully-managed in-memory NoSQL databases on AWS, Azure, GCP, and Digital Ocean and can be used as a cache, database, streaming engine, or message broker. + +## Create a Choreo-Managed Cache + +Follow the steps below to create a Choreo-Managed Cache: + +1. Sign in to the Choreo Console at [https://console.choreo.dev/](https://console.choreo.dev). +2. In the header, click the **Organization** list. This opens the organization home page. +3. In the left navigation menu, click **DB & Services** and then click **Databases**. +4. Click **+ Create** and select **Choreo-Managed Cache** as the data store type. Provide a display name for this server and follow the instructions. +5. Select a preferred cloud provider (AWS, Azure, GCP, or Digital Ocean). + - The cloud provider provisions the compute and storage infrastructure for your data store. + - The functionality remains the same across cloud providers, though service plans and costs may differ. +6. Select a region for your data store. + - Available regions depend on the selected cloud provider. Choreo currently supports US and EU regions across all providers. +7. Select a service plan. + - Service plans vary in terms of dedicated CPU, memory (RAM), and storage space allocated for your data store, as well as high-availability configurations for production use cases. +8. Click **Create**. + +!!! Note - + Once the Choreo-Managed Cache is created, you can add it to the marketplace so developers can discover these and use them in their applications. For more details, see [Add Choreo-Managed Databases and Caches to the Marketplace.](../add-choreo-managed-databases-and-caches-to-the-marketplace) + +## Connect to your Choreo-Managed Cache + +To connect to your Choreo-Managed Cache, follow these guidelines: + +- Choreo-Managed Cache instances accept traffic from the internet by default. You can restrict access to specific IP addresses and CIDR blocks under **Advanced Settings**. +- Use any legacy Redis® OSS compatible driver (in any programming language) to connect to your Choreo-Managed Cache. +- You can find the connection parameters in the **Overview** section in the Choreo Console. Note that Choreo-Managed Cache enforces TLS. + +## High availability and automatic backups + +The high availability and the automatic backup retention periods for a Choreo-Managed Cache can vary as follows depending on the service plan you select. + +| Service plan | High availability | Backup features | Backup history | +| ------------ | -------------------------------------------------------------------------------------------------------------------| ---------------------------------------- | -------------- | +| Hobbyist | Single-node with limited availability. | Single backup only for disaster recovery | None | +| Startup | Single-node with limited availability. | Single backup only for disaster recovery | 1 day | +| Business | Two-node (primary + standby) with higher availability (automatic failover if the primary node fails). | Automatic backups | 3 days | +| Premium | Three-node (primary + standby + standby) with highest availability (automatic failover if the primary node fails). | Automatic backups | 13 days | + +In general, service plans are recommended for production scenarios due to the following reasons: + +- Provides another physical copy of the data in case of hardware, software, or network failures. +- Reduces the data loss window in disaster scenarios. +- Ensures quicker restoration with controlled failover in case of failures, as the standby is already installed and running. + +### Automatic backups + +- Choreo runs full backups daily to automatically backup Choreo-Managed Caches and has write-ahead logs (WAL) copied at 5-minute intervals or for every new file generated. +- Choreo encrypts all backups at rest. +- Choreo automatically handles outages and software failures by replacing broken nodes with new ones that resume correctly from the point of failure. The impact of a failure will depend on the number of available standby nodes in the data store. + +### Failure recovery + +- **Minor failures**: Choreo automatically handles minor failures such as service process crashes or temporary loss of network access in all plans without requiring significant changes to the service deployment. Choreo automatically restores the service to normal operation once it automatically restarts the crashed process or when it restores the network access. + +- **Severe failures**: Failures such as losing a node entirely in case of hardware or severe software problems, require more drastic recovery measures. The monitoring infrastructure automatically detects a failing node when the node starts reporting issues in the self-diagnostics or when it stops communicating. In such cases, the monitoring infrastructure automatically schedules a new replacement node to be created. + - In the event of a data store failover, the service URI of your service remains the same; only the IP address will change to point to the new primary node. + - Hobbyist and Startup plans provide a single node, and in case of failure, a new node starts up, restores its state from the latest available backup, and resumes serving traffic. + - As there is just a single/primary node, the caching service becomes unavailable for the duration of the restoration operation. Therefore, all write operations made since the last backup will be lost. + +## Limitations + +### Connection limits + +The number of simultaneous connections in a Choreo-Managed Cache depends on the total available memory on the server instances. + +You can use the following to estimate: + +``` +max_number_of_connections = 4 x m +``` + +Here, `m` represents the memory in megabytes, where at least 10,000 connections are available, even on the smallest servers. +For example, on a server with 4GB memory (4,096 MB), the simultaneous connections are: + +``` +4 x 4096 = 16384 // 16k connections +``` + +This number is estimated by the exact available memory so it can vary between different plans and cloud providers. To see the exact maximum connections allowed, use the \* redis-cli and info command as follows: + +``` +echo "info" | redis-cli -u REDIS_URI | grep maxclients +``` + +### Restricted commands + +To maintain the stability and security of a managed environment, Choreo restricts certain commands on Choreo-Managed Cache services. + +!!! note "Support for Lua scripts on Choreo-Managed Cache" + - Choreo-Managed Cache has built-in support for running Lua scripts to perform various actions directly on the server. Scripting is typically controlled using the `EVAL`, `EVALSHA`, and `SCRIPT LOAD` commands. + - For all newly-created cache instances, `EVAL`, `EVALSHA`, and `SCRIPT LOAD` commands are enabled by default. + +The following commands are disabled on Choreo: + +- `bgrewriteaof`: Initiates a background append-only file rewrite. +- `cluster`: Manages Caching cluster commands. +- `command`: Provides details about all Caching commands. +- `debug`: Contains sub-commands for debugging Caching. +- `failover`: Manages manual failover of a master to a replica. +- `migrate`: Atomically transfers a key from one caching instance to another. +- `role`: Returns the role of the instance in the context of replication. +- `slaveof`: Makes the server a replica of another instance, or promotes it as master. +- `acl`: Manages caching access control lists. +- `bgsave`: Creates a snapshot of the data set into a dump file. +- `config`: Alters the configuration of a running caching server. +- `lastsave`: Returns the UNIX timestamp of the last successful save to disk. +- `monitor`: Streams back every command processed by the Caching server. +- `replicaof`: Makes the server a replica of another instance. +- `save`: Synchronously saves the dataset to disk. +- `shutdown`: Synchronously saves the dataset to disk and then shuts down the server. + +The following `eval` commands are also disabled: + +- `eval`: Executes a Lua script server-side. +- `eval_ro`: Read-only variant of the eval command. +- `evalsha`: Executes a script cached on the server side by its SHA1 digest. +- `evalsha_ro`: Read-only variant of the evalsha command. +- `fcall`: Calls a Caching function. +- `fcall_ro`: Read-only variant of the fcall command. +- `function`: Manages Caching functions. +- `script`: Manages the script cache. diff --git a/en/pe-docs/docs/db-and-services/databases/choreo-managed-databases-and-caches.md b/en/pe-docs/docs/db-and-services/databases/choreo-managed-databases-and-caches.md new file mode 100644 index 000000000..50369f335 --- /dev/null +++ b/en/pe-docs/docs/db-and-services/databases/choreo-managed-databases-and-caches.md @@ -0,0 +1,33 @@ +# Choreo-Managed Databases, Vector Databases, and Caches + +Choreo allows you to create PostgreSQL and MySQL databases as well as Choreo-Managed Cache instances on all major cloud providers (AWS, Azure, GCP, and DigitalOcean) as fully Choreo-managed platform services. +These databases and caches can be seamlessly provisioned to offer persistence and caching capabilities for all your Choreo components. Choreo provides various service plans for each type, ranging from smaller instances for development purposes to production-grade databases with automatic backups and high-availability multi-nodes. + +!!! info "Note" + - The capability to create Choreo-managed databases, vector databases, and cache services is available only for paid Choreo users. + - Billing for these services will be included in your Choreo subscription, with pricing varying based on the service plan of the resources you create. For more details, see [Choreo Platform Services Billing](../../references/choreo-platform-services-billing-and-upgrades.md#platform-service-billing-information). + +!!!Tip "Explore the free trial" + Choreo provides a 7-day free trial for all database types on the 'Hobbyist' service plan, available to free-tier users. + +## PostgreSQL on Choreo + +PostgreSQL (also known as Postgres), is an open-source object-relational database management system. You can create PostgreSQL databases on Choreo as fully Choreo-managed, flexible SQL databases that are ideal for both structured and unstructured data. If you want to perform an efficient vector similarity search, you can create a PostgreSQL vector database. + +- [Create a PostgreSQL database on Choreo](./choreo-managed-postgresql-databases.md) + +## MySQL on Choreo + +MySQL is a user-friendly, flexible, open-source relational database management system with a well-established history in the SQL database realm. Choreo allows you to swiftly create fully Choreo-managed MySQL databases, enabling rapid setup and utilization. + +- [Create a MySQL database on Choreo](./choreo-managed-mysql-databases.md) + +## Choreo-Managed Cache + +A fully-managed cache compatible with legacy Redis® OSS. A versatile, in-memory NoSQL database that serves as a cache, database, streaming engine, and message broker. Choreo-managed Cache allows you to have fully-managed instances that can be swiftly provisioned and integrated into your applications within minutes. + +- [Create a Choreo-managed Cache](./choreo-managed-caches.md) + + + PostgreSQL, MySQL, and Redis® are trademarks and property of their respective owners. All product and service names used in this documentation are for identification purposes only. + diff --git a/en/pe-docs/docs/db-and-services/databases/choreo-managed-mysql-databases.md b/en/pe-docs/docs/db-and-services/databases/choreo-managed-mysql-databases.md new file mode 100644 index 000000000..e18cc23a7 --- /dev/null +++ b/en/pe-docs/docs/db-and-services/databases/choreo-managed-mysql-databases.md @@ -0,0 +1,77 @@ +# Choreo-managed MySQL Databases + +MySQL on Choreo offers fully managed, flexible relational databases on AWS, Azure, GCP, and Digital Ocean. + +## Create a Choreo-managed MySQL database + +Follow the steps below to create a Choreo-managed MySQL database: + +1. Sign in to the [Choreo Console](https://console.choreo.dev/). +2. In the Choreo Console header, go to the **Organization** list and select your organization. +3. In the left navigation menu, click **DB & Services** and then **Databases**. +4. Click **Create** and select **MySQL** as the database type. Provide a display name for this server and follow the instructions. +5. Select your preferred cloud provider from AWS, Azure, GCP, and Digital Ocean. + - Choreo uses the cloud provider to provision the compute and storage infrastructure for your database. + - There is no functional difference between databases created on different cloud providers, apart from changes to service plans (and associated costs). +6. Choose the region for your database. + - Available regions will depend on the selected cloud provider. Choreo currently supports US and EU regions across all providers. +7. Select the service plan. + - Service plans vary in the dedicated CPU, memory (RAM), storage space allocated for your database, the backup retention periods, and high-availability configurations for production use cases. + +!!! Note - + Once the database is created, you can add it to the marketplace so developers can discover these databases and use them in their applications. For more details, see [Add Choreo-Managed Databases and Caches to the Marketplace.](../add-choreo-managed-databases-and-caches-to-the-marketplace) + +## Connect to your Choreo-managed MySQL database + +To connect to your Choreo-managed MySQL database, consider the following guidelines: + +- MySQL databases accept traffic from the internet by default. You can restrict access to specific IP addresses and CIDR blocks under **Advanced Settings**. + +- You can use any MySQL driver, ORM, or supported generic SQL library (may depend on the programming language) to connect to the database. +- You can find the connection parameters in the **Overview** section in the Choreo Console under the relevant database. + +## High Availability and Automatic Backups + +The high availability characteristics and the automatic backup retention periods for Choreo-managed MySQL databases vary based on your service plan as explained below: + +| Service Plan | High Availability | Backup Retention Time | +|--------------|--------------------------------------------------------------------|-----------------------| +| Hobbyist | Single-node with limited availability | None | +| Startup | Single-node with limited availability | 2 days | +| Business | Two-node (primary + standby) with higher availability | 14 days | +| Premium | Three-node (primary + standby + standby) with highest availability | 30 days | + +In general, we recommend service plans for production scenarios for multiple reasons: +- Provides another physical copy of the data in case of hardware, software, or network failures. +- Typically reduces the data loss window in disaster scenarios. +- Provides a quicker time to restore with a controlled failover in case of failures, as the standby is already installed and running. + +### Automatic Backups + +- Choreo runs full backups daily to automatically back up Choreo-managed MySQL databases and record binary logs continuously. +Choreo encrypts all backups at rest. + +- Choreo automatically handles outages and software failures by replacing broken nodes with new ones that resume correctly from the point of failure. The impact of a failure will depend on the number of available standby nodes in the database. + +## Connection Limits + +The maximum number of simultaneous connections to MySQL databases is fixed for each service plan and depends on how much RAM your service plan offers. + +!!! note + An `extra_connection` with a value of `1` is added for system processes for all MySQL databases, regardless of the service plan. + +### For plans under 4 GiB RAM + +For plans under 4 GiB of RAM, the number of allowed connections is `75` per GiB: + +``` +max_connections = 75 x RAM + extra_connection +``` + +### For plans with over 4 GiB RAM: + +For plans with 4 GiB or more RAM, the number of allowed connections is `100` per GiB: + +``` +max_connections = 100 x RAM + extra_connection +``` diff --git a/en/pe-docs/docs/db-and-services/databases/choreo-managed-postgresql-databases.md b/en/pe-docs/docs/db-and-services/databases/choreo-managed-postgresql-databases.md new file mode 100644 index 000000000..fceb42c80 --- /dev/null +++ b/en/pe-docs/docs/db-and-services/databases/choreo-managed-postgresql-databases.md @@ -0,0 +1,85 @@ +# Choreo-Managed PostgreSQL Databases and Vector Databases + +PostgreSQL on Choreo offers fully Choreo-managed, efficient object-relational databases on AWS, Azure, GCP, and Digital Ocean. Additionally, Choreo allows you to create fully-managed PostgreSQL vector databases if you want to perform efficient vector similarity search. + +## Create a Choreo-managed PostgreSQL database + +Follow the steps below to create a Choreo-managed PostgreSQL database: + +1. Sign in to the Choreo Console at [https://console.choreo.dev/](https://console.choreo.dev/). +2. In the header, click the **Organization** list. This opens the organization home page. +3. In the left navigation menu, click **DB & Services** and then **Databases**. +4. Click **Create** and select **PostgreSQL** as the database type. Provide a display name for this server and follow the instructions. +5. Select your preferred cloud provider from AWS, Azure, GCP, or Digital Ocean. + - The cloud provider is used to provision the compute and storage infrastructure for your database. + - There is no functional difference between databases created on different cloud providers, apart from changes to service plans (and associated costs). +6. Choose the region for your database. + - Available regions will depend on the selected cloud provider. Choreo currently supports US and EU regions across all providers. +7. Select the service plan. + - Service plans vary in the dedicated CPU, memory (RAM), storage space allocated for your database, the backup retention periods, and high-availability configurations for production use cases. + +## Create a Choreo-managed PostgreSQL vector database + +Follow the steps below to create a Choreo-managed PostgreSQL vector database: + +1. Sign in to the Choreo Console at [https://console.choreo.dev/](https://console.choreo.dev/). +2. In the header, click the **Organization** list. This opens the organization home page. +3. In the left navigation menu, click **DB & Services** and then **Vector Databases**. +4. Follow steps 4 onwards in the [Create a Choreo-managed PostgreSQL database](#create-a-choreo-managed-postgresql-database) section. + +!!! Note - + Once the database is created, you can add it to the marketplace so developers can discover these databases and use them in their applications. For more details, see [Add Choreo-Managed Databases and Caches to the Marketplace.](../add-choreo-managed-databases-and-caches-to-the-marketplace) + + +## Connecting to your Choreo-managed PostgreSQL database + +To connect to your Choreo-managed PostgreSQL database, consider the following guidelines: + +- PostgreSQL databases accept traffic from the internet by default. You can restrict access to specific IP addresses and CIDR blocks under **Advanced Settings**. +- You can use any PostgreSQL driver, ORM, or supported generic SQL library (may depend on the programming language) to connect to the database. +- The connection parameters can be found in the **Overview** section in the Choreo Console under the relevant database. + + +## High Availability and Automatic Backups + +The high availability characteristics and the automatic backup retention periods for Choreo-managed PostgreSQL databases vary based on the selected service plan as shown below. + +| Service Plan | High Availability | Backup Retention Time | +|--------------|--------------------------------------------------------------------|-----------------------| +| Hobbyist | Single-node with limited availability | None | +| Startup | Single-node with limited availability | 2 days | +| Business | Two-node (primary + standby) with higher availability | 14 days | +| Premium | Three-node (primary + standby + standby) with highest availability | 30 days | + +Service plans with standby nodes are generally recommended for production scenarios for multiple reasons: +- Provides another physical copy of the data in case of hardware, software, or network failures. +- Typically reduces the data loss window in disaster scenarios. +- Provides a quicker time to restore with a controlled failover in case of failures, as the standby is already installed and running. + +### Automatic Backups + + +- Choreo runs full backups daily to automatically back up Choreo-managed PostgreSQL databases and copies the write-ahead logs (WAL) at 5-minute intervals or for every new file generated. +Choreo encrypts all backups at rest. + +- Choreo automatically handles outages and software failures by replacing broken nodes with new ones that resume correctly from the point of failure. The impact of a failure will depend on the number of available standby nodes in the database. + +### Failure Recovery + +- **Minor failures**: Choreo automatically handles minor failures such as service process crashes or temporary loss of network access in all plans without requiring significant changes to the service deployment. Choreo automatically restores the service to normal operation once Choreo automatically restarts the crashed process or when Choreo restores the network access. + +- **Severe failures**: To handle severe failures such as losing a node entirely in case of hardware or severe software problems, requires more drastic recovery measures. The monitoring infrastructure automatically detects a failing node, both when the node starts reporting issues in the self-diagnostics or when it stops communicating. In such cases, the monitoring infrastructure automatically schedules a new replacement node to be created. +> - In the event of database failover, the Service URI of your service remains the same; only the IP address will change to point to the new primary node. +> - Hobbyist and Startup plan provide a single node, and in case of failure, a new node starts up, restores its state from the latest available backup, and resumes serving traffic. +In this plan, as there is just a single node providing the service, the service will become unavailable for the duration of the restoration. In addition, any write operations made since the backup of the latest WAL file will be lost. Typically, this time window is limited to either five minutes of time or one WAL file. + +## Connection limits + +The following connection limits apply to Choreo-managed PostgreSQL databases based on the selected service plan. + +| Service Plan | Max Connections | +|----------------------------|-----------------| +| Hobbyist | 25 | +| Startup/Business/Premium-4 | 100 | +| Business-16 | 400 | +| Premium-8 | 200 | diff --git a/en/pe-docs/docs/db-and-services/external-services/integrate-and-manage-gen-ai-services.md b/en/pe-docs/docs/db-and-services/external-services/integrate-and-manage-gen-ai-services.md new file mode 100644 index 000000000..346148b07 --- /dev/null +++ b/en/pe-docs/docs/db-and-services/external-services/integrate-and-manage-gen-ai-services.md @@ -0,0 +1,91 @@ +# Integrate and Manage Generative AI Services + +Generative AI (GenAI) services leverage advanced machine learning models to create original content such as text, images, music, or code, by identifying and learning patterns from existing data. Powered by deep neural networks and other machine learning models, these services can generate human-like outputs in various formats. This versatility makes GenAI ideal for tasks such as content creation, image generation, conversation automation, etc. + +Choreo enables seamless integration with GenAI services, allowing the developers to incorporate these capabilities within their applications. + +## Register a GenAI service + +To seamlessly integrate a GenAI service into an application deployed in Choreo, you need to register it. Once registered, the service becomes available in the Internal Marketplace, allowing developers to consume it via a Connection. + +You can register a GenAI service at two levels: + + - Organization level: This makes the service accessible from any project within the organization. + - Project level: This restricts the service to a specific project. + +### Prerequisites + +Before registering a GenAI service, obtain the following details from the service provider: + - API key. + - Service URL. + - Other necessary parameters. For example, client credentials. + +To register a GenAI service, follow these steps: + +!!! note + Ensure that you register the service at the appropriate level depending on the usage. If the service must be shared among multiple projects, register it at the organization level. Otherwise, register it at the project level. + +### Step 1: Select a service provider + +1. Sign in to the [Choreo Console](https://console.choreo.dev/). +2. Follow one of these steps depending on your requirements: + - To register a GenAI service at the organization level, go to the Choreo Console header and select your organization from the **Organization** list. + - To register a GenAI service at the project level, go to the Choreo Console header and select your project from the **Project** list. +3. In the left navigation menu, click **DB & Services** and then click **GenAI Services**. +4. Click **+ Register**. +5. Select a service provider. +6. Click **Next**. + +### Step 2: Provide service details + +1. Under **Register Service**, enter the following details for the service: + - A **Name** and **Version**. + - The **Service URL**. + +2. Click **Next**. + +### Step 3: Add configurations + +1. Under **Add Configurations**, enter details for the service. + + !!! note + - The configuration details to enter vary depending on the selected service provider. + - To successfully register a service, ensure you provide all the required configurations. + +2. Click **Register**. + +Once registered, the GenAI service is automatically listed in the Internal Marketplace. + +If you want to remove the service from the Internal Marketplace, see [Remove a GenAI service from the Internal Marketplace](#remove-a-genai-service-from-the-internal-marketplace). + + +## Manage GenAI services + +When you create a GenAI service, it gets listed in the **GenAI Services** list. + +### View or update GenAI service details + +To view or update a GenAI service, follow these steps. + +1. Sign in to the [Choreo Console](https://console.choreo.dev/). +2. In the left navigation menu, click **DB & Services** and then click **GenAI Services**. This lists all the GenAI services you have created. +3. Click on a service to view or update its details. + - **General Details**: Displays service metadata. For example, the service name, overview, labels, etc. + - **Service Definition**: Displays the service definition. To update the definition, click **Upload** and select the new definition file. + +### Add a GenAI service to the Internal Marketplace + +!!! info + To add a GenAI service to the Internal Marketplace, you must provide all the required configurations. + +1. In the Choreo Console left navigation menu, click **DB & Services** and then click **GenAI Services**. +2. Click on the service you want to add to the Internal Marketplace. +3. Click **Add to Marketplace**. + +### Remove a GenAI service from the Internal Marketplace + +1. In the Choreo Console left navigation menu, click **DB & Services** and then click **GenAI Services**. +2. Click on the service you want to remove from the Internal Marketplace. +3. Click **Remove from Marketplace**. + +This removes the service from the Internal Marketplace. Therefore, the service will not be available to consume via a Connection. However, the connections created before removal will continue to work as expected. diff --git a/en/pe-docs/docs/db-and-services/external-services/integrate-and-manage-third-party-services.md b/en/pe-docs/docs/db-and-services/external-services/integrate-and-manage-third-party-services.md new file mode 100644 index 000000000..f05e1348b --- /dev/null +++ b/en/pe-docs/docs/db-and-services/external-services/integrate-and-manage-third-party-services.md @@ -0,0 +1,118 @@ +# Integrate and Manage Third-Party Services + +Third-party services are external applications, platforms, or APIs you can integrate with your system to enhance its functionality, extend capabilities, or provide specialized features. These services are developed and maintained by external entities, providing expertise in specific domains outside your application's core focus. Once the third party services are registered, the developers can discover these third party APIs and use them in their applications. + +The following topics walk you through the steps to seamlessly register, manage, and consume third-party services, adhering to API-first principles. + +## Register a third-party service in Choreo + +To use a third-party service in Choreo, you need to register it. Once registered, the service becomes available in the Internal Marketplace, allowing developers to consume it via a Connection. + +You can register a third-party service at two levels: + + - Organization level: This makes the service accessible from any project within the organization. + - Project level: This restricts the service to a specific project. + +Choreo allows you to register the following third-party service types: + + - REST APIs + - GraphQL APIs + - Asynchronous APIs + - SOAP + - gRPC + +### Prerequisites + +Before registering a third-party service, obtain the following details from the service provider: + + - API specification. For example, OpenAPI or GraphQL schema. + - Service URL. + - Other necessary parameters. For example, client credentials, API keys, etc. + +To register a third-party service, follow these steps: + +!!! note + Ensure you register the service at an appropriate level depending on the service usage. If the service must be shared among multiple projects, register it at the organization level. Otherwise, register it at the project level. + +### Step 1: Provide basic details + +1. Sign in to the [Choreo Console](https://console.choreo.dev/). +2. Follow one of these steps depending on your requirement: + - To register a third-party service at the organization level, go to the Choreo Console header and select your organization from the **Organization** list. + - To register a third-party service at the project level, go to the Choreo Console header and select your project from the **Project** list. +3. In the left navigation menu, click **DB & Services** and then click **Third-Party Services**. +4. Click **+ Register**. +5. Provide details for the service: + - Enter a **Name** and **Version**. + - Upload the service definition file. This automatically detects the service type. + - Verify the **Service Type**. +6. Click **Define Endpoints**. + +Now you are ready to define endpoints for the service. + +### Step 2: Define service endpoints + +An endpoint is a set of parameters required to connect to a service. The required parameters are service URL, API key header, etc. +These parameters provide the necessary information for a client application to interact with the service. + +To define service endpoints, follow these steps: + +1. Under **Define New Endpoint**, + - Enter a **Name** for the endpoint. + - Enter the **Endpoint URL**. + +2. Under **Additional Parameters**, add any other parameters required to connect to the service. + For example, API key, authorization token, etc. + + !!! note + - If you want to keep a parameter confidential, select the **Secret** checkbox. + - If there are multiple endpoints, the parameter names will be the same for all the endpoints. + +3. Select the environments where the endpoint should be accessible. + + !!! note + Service consumers can create connections to the endpoint only from the selected environments. + +4. Click **OK**. + +5. If you want to add more endpoints, click **+ New Endpoint** and repeat steps 1 to 4. + +6. Click **Register**. + +When you define all required parameter values for at least one endpoint, the service will be automatically listed in the Internal Marketplace. Otherwise, you must [add the service to the Internal Marketplace](#add-a-third-party-service-to-the-internal-marketplace) after providing the endpoint values. + +If you want to remove a third-party service from the Internal Marketplace, see [Remove a third-party service from the Internal Marketplace](#remove-a-third-party-service-from-the-internal-marketplace). + +For details on managing third-party services, see [Manage third-party service](#manage-third-party-services). + +## Manage third-party services + +When you create a third-party service, it gets listed in the **Third-Party Services** list. + +### View or update third-party service details + +To view or update a third-party service, follow these steps. + +1. Sign in to the [Choreo Console](https://console.choreo.dev/). +2. In the left navigation menu, click **DB & Services** and then click **Third-Party Services**. This lists all the third-party services you have created. +3. Click on a service to view or update its details. + - **General Details**: Displays service metadata. For example, the service name, overview, labels, etc. + - **Service Definition**: Displays the service definition. To update the definition, click **Upload** and select the new definition file. + - **Endpoints**: Displays service endpoint details. You can add, modify, or delete service endpoints. + +### Add a third-party service to the Internal Marketplace + +!!! info + To add a third-party service to the Internal Marketplace, you must provide all required parameters for at least one endpoint. + +1. In the Choreo Console left navigation menu, click **DB & Services** and then click **Third-Party Services**. +2. Click on the service you want to add to the Internal Marketplace. +3. Click **Add to Marketplace**. + +### Remove a third-party service from the Internal Marketplace + +1. In the Choreo Console left navigation menu, click **DB & Services** and then click **Third-Party Services**. +2. Click on the service you want to remove from the Internal Marketplace. +3. Click **Remove from Marketplace**. + +This removes the service from the Internal Marketplace. Therefore, the service will not be available to consume via a Connection. However, the connections created before removal will continue to work as expected. diff --git a/en/pe-docs/docs/db-and-services/message-brokers/choreo-managed-message-brokers.md b/en/pe-docs/docs/db-and-services/message-brokers/choreo-managed-message-brokers.md new file mode 100644 index 000000000..49db0d3d8 --- /dev/null +++ b/en/pe-docs/docs/db-and-services/message-brokers/choreo-managed-message-brokers.md @@ -0,0 +1,13 @@ +# Choreo Managed Message Brokers + +Choreo allows you to create Apache Kafka services across major cloud providers (AWS, Azure, GCP, and DigitalOcean) as Choreo-managed platform services for your message brokering needs. These fully managed Kafka instances can seamlessly integrate with Choreo components, providing scalable messaging for real-time data pipelines and event-driven applications. Choreo offers multiple Kafka service plans, ranging from lightweight instances for development purposes to production-grade clusters with automatic backups, high-availability multi-nodes, and partitioning. + +!!! info "Note" + - Kafka service creation is available only for paid Choreo organizations. + - Kafka service billing will be included in your Choreo subscription, with pricing varying based on the service plan of the resources you create. For more details, see [Choreo Platform Services Billing](../../references/choreo-platform-services-billing-and-upgrades.md#platform-service-billing-information). + +## Apache Kafka on Choreo + +Apache Kafka is an open-source platform for real-time event streaming and handling large-scale, event-driven data. You can create Kafka services on Choreo as fully-managed, scalable, message brokers, ideal for handling large volumes of event-driven data. + +- [Create a Choreo-managed Kafka service](./create-choreo-managed-kafka-services.md) diff --git a/en/pe-docs/docs/db-and-services/message-brokers/configure-a-kafka-service.md b/en/pe-docs/docs/db-and-services/message-brokers/configure-a-kafka-service.md new file mode 100644 index 000000000..b556bdaeb --- /dev/null +++ b/en/pe-docs/docs/db-and-services/message-brokers/configure-a-kafka-service.md @@ -0,0 +1,75 @@ +# Configure a Kafka Service + +After creating a Kafka service, you can create topics, configure advanced settings, and manage access to ensure secure and efficient message processing. + +## Create a Kafka topic + +Kafka topics are logical channels used to organize and transfer messages between producers and consumers. They form the core of Kafka's architecture, enabling data streams to be written and read. Kafka topics can also be partitioned to improve scalability and fault tolerance. + +To create a Kafka topic, follow these steps: + +1. Sign in to the Choreo Console at [https://console.choreo.dev/](https://console.choreo.dev). +2. In the header, click the **Organization** list. This opens the organization home page. +3. In the left navigation menu, click **DB & Services** and then click **Message Brokers**. +4. In the **Message Brokers** list, click the Kafka service for which you want to create a topic. +5. Click the **Topics** tab. +6. Click **+ Create**. +7. In the **Create Topic** dialog that opens, + 1. Enter a name for the topic. + 2. To configure advanced settings, click to expand **Advanced Configurations** and apply the required settings. For details, see [Advanced topic configurations](#advanced-topic-configurations). +8. Click **Create**. + +### Advanced topic configurations + +Choreo allows you to customize settings for Kafka topics, including the number of partitions, replication factor, cleanup policy, retention size (bytes), retention duration (hours), and the minimum number of in-sync replicas. + +**Cleanup Policy:** Determines how messages that reach their retention limit are handled. There are three options: + +- Delete (default): Messages are removed when the retention limit is exceeded. +- Compact: Retains only the latest record for each unique key, ensuring only the most recent data is kept. +- Compact and Delete: Combines both approaches, where old records are deleted based on retention limits, but the latest record for each key is retained. + +**Replication:** Sets the number of partition copies to ensure data durability. The default is 3. + +**Partitions:** Defines the number of segments the topic should be divided into for parallel processing. The default is 1 partition. + +**Retention Bytes:** Sets the maximum size of retained messages. Older messages are discarded on reaching this limit. The default is unlimited (-1). + +**Retention Hours:** Defines the retention period for messages before deletion. The default is 168 hours (7 days). + +**Min In-Sync Replicas:** Specifies the minimum number of replicas that must acknowledge a write for it to be considered successful. The default is 2. + +## Manage service users and access control lists + +Choreo-managed Kafka services use access control lists (ACLs) and user definitions to control access to topics. You can manage users and ACL entries from the corresponding tabs on the Kafka service details page. + +### Manage users + +To manage users for a Choreo-managed Kafka service, follow these steps: + +1. Sign in to the Choreo Console at [https://console.choreo.dev/](https://console.choreo.dev). +2. In the header, click the **Organization** list. This opens the organization home page. +3. In the left navigation menu, click **DB & Services** and then click **Message Brokers**. +4. In the **Message Brokers** list, click the Kafka service for which you want to manage users. +5. Click the **Users** tab. +6. Click **+ Add User**, specify a username, and then click **Add**. + +By default, new users do not have any permissions. You can grant necessary permissions to users through access control lists (ACLs). + +### Configure access control lists (ACLs) + +An ACL entry defines access permission for a user. Each entry includes: + + - Username: The username. + - Topic: The associated Kafka topic to grant access to the user. + - Permission: The permission to grant the user. + +To add an ACL entry, follow these steps: + +1. Sign in to the Choreo Console at [https://console.choreo.dev/](https://console.choreo.dev). +2. In the header, click the **Organization** list. This opens the organization home page. +3. In the left navigation menu, click **DB & Services** and then click **Message Brokers**. +4. In the **Message Brokers** list, click the Kafka service for which you want to add an ACL entry. +5. Click the **Access Control List** tab. +6. Click **+ Add Entry**, select a username, topic, and permission. +7. Click **Add**. diff --git a/en/pe-docs/docs/db-and-services/message-brokers/create-choreo-managed-kafka-services.md b/en/pe-docs/docs/db-and-services/message-brokers/create-choreo-managed-kafka-services.md new file mode 100644 index 000000000..8bbbd149b --- /dev/null +++ b/en/pe-docs/docs/db-and-services/message-brokers/create-choreo-managed-kafka-services.md @@ -0,0 +1,33 @@ +# Create Choreo-Managed Kafka Services + +Kafka on Choreo offers fully managed, distributed message broker services across AWS, Azure, GCP, and DigitalOcean. These services are designed to handle high-throughput, fault-tolerant data streaming use cases such as real-time analytics, event sourcing, and log aggregation. + +!!! info "Note" + - Kafka service creation is available only for paid Choreo organizations. + - Kafka service billing will be included in your Choreo subscription, with pricing varying based on the service plan of the resources you create. For more details, see [Choreo Platform Services Billing](../../references/choreo-platform-services-billing-and-upgrades.md#platform-service-billing-information). + +## Create a Choreo-managed Kafka service + +Follow the steps below to create a Choreo-managed Kafka service: + +1. Sign in to the Choreo Console at [https://console.choreo.dev/](https://console.choreo.dev). +2. In the header, click the **Organization** list. This opens the organization home page. +3. In the left navigation menu, click **DB & Services** and then click **Message Brokers**. +4. Click **+ Create**. +5. Specify a display name for the Kafka service and click **Next**. +6. Select your preferred cloud provider from AWS, Azure, GCP, or Digital Ocean. + - The cloud provider provisions the computing and storage infrastructure for your Kafka service. + - There is no functional difference between Kafka services across providers except for variations in service plans and associated costs. +7. Select a region for your Kafka service. + - Available regions depend on the selected cloud provider. Choreo currently supports US, EU, and AU regions across all providers. +8. Select a service plan. + - Service plans differ based on the allocation of CPU, memory (RAM), and storage for your Kafka server, as well as backup retention periods and high-availability options suited for production environments. +9. Click **Create**. This creates the Kafka service and takes you to the **Overview** tab on the service details page. + +## Connect to your Choreo-managed Kafka service + +- By default, Kafka services accept traffic from the internet. However, if you want to restrict access to specific IP addresses or CIDR blocks, you can configure the necessary advanced settings. + +- Choreo secures Kafka connections via client certificate authentication. + +- To connect to your Choreo-managed Kafka service, use the connection parameters from the **Overview** tab on the service details page. diff --git a/en/pe-docs/docs/db-and-services/message-brokers/monitor-a-kafka-service.md b/en/pe-docs/docs/db-and-services/message-brokers/monitor-a-kafka-service.md new file mode 100644 index 000000000..21238255f --- /dev/null +++ b/en/pe-docs/docs/db-and-services/message-brokers/monitor-a-kafka-service.md @@ -0,0 +1,31 @@ +# Monitor a Kafka Service + +You can monitor the health and performance of your Kafka services via the service metrics and service logs. + +## Service metrics + +Service metrics provide real-time insights into the performance of your Kafka service. + +To view service metrics for a Kafka service, follow the steps given below: + +1. Sign in to the [Choreo Console](https://console.choreo.dev/). +2. In the Choreo Console header, go to the **Organization** list and select your organization. +3. On the left navigation menu, click **DB & Services** and then click on **Message Brokers**. +4. Click on the required message broker and go to the **Metrics** tab on the service details page. + +The service metrics include the following: + +- **CPU Usage %**: Displays the percentage of CPU resources consumed by the service. +- **Disk Usage %**: Represents the percentage of disk space utilized by the service. +- **Disk IO Reads**: Displays the input/output operations per second (IOPS) for disk reads. +- **Disk IO Writes**: Displays the input/output operations per second (IOPS) for disk writes. +- **Load Average**: Displays the 5-minute average CPU load, indicating the system's computational load. +- **Memory Available %**: Represents the percentage of memory resources utilized by the service. +- **Network Received**: Indicates the volume of network traffic received by the service in bytes per second. +- **Network Sent**: Indicates the amount of network traffic transmitted by the service in bytes per second. + +## Service logs + +Service logs provide a detailed record of Kafka service activity, such as producer and consumer operations, connection statuses, and error reports. These logs are essential for troubleshooting issues and analyzing message flow. Logs are retained for up to 4 days. + +To view Choreo-managed Kafka service logs, go to the **Logs** tab on the service details page. diff --git a/en/pe-docs/docs/devops/cd-pipelines/deploying-application-using-choreo-cd-pipeline.md b/en/pe-docs/docs/devops/cd-pipelines/deploying-application-using-choreo-cd-pipeline.md new file mode 100644 index 000000000..c3198bc64 --- /dev/null +++ b/en/pe-docs/docs/devops/cd-pipelines/deploying-application-using-choreo-cd-pipeline.md @@ -0,0 +1,65 @@ +# Deploy Applications using Choreo CD Pipeline + +Using Choreo, you can easily deploy applications written in different language frameworks (such as Java, Go, NodeJS, Python, etc.) on shared or private data planes. + +After building your application, you can deploy it from the **CD Pipelines** page. On this page, you can access the CD pipeline of the selected component. + +## Trigger a deployment + +Follow below steps to deploy a component, + +1. Sign in to the [Choreo Console](https://console.choreo.dev/). +2. In the Choreo Console top navigation menu, select the **Organization**, then the **Project** and finally the relevant **Component**. +3. From the left navigation, Click **DevOps** and then click **CD Pipelines** +4. The setup card will contain the latest built image + + !!! Tip - + Click on the image in the **Setup** card to select a different image instead of the latest build. + +5. To deploy your application, you can use one of the following options : + + 1. **Configure & Deploy**: This option allows you to set up specific configurations for your component before deploying it. In the subsequent steps after clicking **Configure & Deploy**, you can set environment variables, configure file mounts, and adjust endpoint settings. + + - Environment variables : Apply environment-specific variables via the **Environment Configurations** pane + - File mounts : Apply a file mount via the **File Mount** pane + - Endpoint settings: Configure endpoint settings via the **Endpoint Details** pane. + + 2. **Deploy**: This option initiates the deployment process using the existing configurations without making any changes. + +## Auto Deploy on Build + +When **Auto Deploy on Build** is enabled, it triggers an automatic deployment of your application to the first environment upon the completion of each successful build. + +!!! Note - + The **Auto Deploy on Build** feature, is disabled by default. To enable this feature, toggle on the Auto Deploy on Build option in the **Setup** card. + +## Promoting a component to a higher environment + +You can go to the CD Pipelines page of a component and manually promote it across environments. + +Follow below steps to promote a component to a higher level environment: + +1. Sign in to the [Choreo Console](https://console.choreo.dev/). +2. In the Choreo Console top navigation menu, select the **Organization**, then the **Project** and finally the relevant **Component**. +3. From the left navigation, Click **DevOps** and then click **CD Pipelines** +4. Click the **Promote** button on the required environment card from which the promotion is initiated. +5. In the **Configuration Types** pane, you can either provide new values for the configurations or use the **Development configuration**. + +!!! Note - + If you have configured any default values for the configurable variables, selecting Use default configuration values allows you to proceed with those values. If not, specify values for the configurable variables. + +6. When promoting the component, you can modify environment-specific configurations (environment variables, file mount etc) in the subsequent steps of the promotion flow. + +7. Click **Promote**. + +!!! Tip - + Choreo supports workflow approvals, allowing organizations to enforce approval processes before a component is promoted to a higher environment. For more details, see [Configure Approvals for Choreo Workflows](../../governance/workflows/configure-approvals-for-choreo-workflows.md) + +## Configurations + +### Environment-Independent Configurations + +These configurations apply to all environments. To change environment-independent configurations, make the necessary configuration changes via the **Setup** card, and then trigger a new deployment to the initial environment. Once deployed, you can promote the component to higher environments. **Endpoint configurations** can be managed from the **Setup** card. + +### Environment-specific configurations +These configurations apply to a particular environment. To change environment-specific configurations, make the necessary configuration changes via the specific environment card, and trigger a new deployment. From the environment card, you can manage **Configs & Secret** and **Scaling** options. diff --git a/en/pe-docs/docs/devops/cd-pipelines/manage-continuous-deployment-pipelines.md b/en/pe-docs/docs/devops/cd-pipelines/manage-continuous-deployment-pipelines.md new file mode 100644 index 000000000..a7675db2c --- /dev/null +++ b/en/pe-docs/docs/devops/cd-pipelines/manage-continuous-deployment-pipelines.md @@ -0,0 +1,111 @@ +# Manage Continuous Deployment Pipelines + +By default, all the organizations in Choreo are provisioned with a default continuous deployment pipeline. + +Environments within an organization are applied to projects in the order specified by the continuous deployment pipeline. The organization's default continuous deployment pipeline is applied to all the projects. You can create additional pipelines and customize the sequence in which environments are applied in projects. + +## Create a new continuous deployment pipeline + +### Prerequisites + +- To create a new continuous deployment pipeline in an organization, you must have the `ENVIRONMENT-MANAGEMENT` permission. By default, `ENVIRONMENT-MANAGEMENT` permission is granted to Admin, Choreo Platform Engineer and Choreo DevOps roles. + +To create a new pipeline, follow the steps given below: + +1. Sign in to [Choreo](https://console.choreo.dev/). +2. In the Choreo Console, go to the top navigation menu and click **Organization**. Then select your organization. +3. In the left navigation menu, click **DevOps** and then click **CD Pipelines**. +4. On the **CD Pipelines** page, click **+ Create Pipeline** and specify the following details required to create a new pipeline: + + - **Name**: A display name for the new pipeline. + - **Mark as Default**: Select if you want to assign this new pipeline as the default pipeline for all new projects. +5. Click **+ Add Environment** and add required environments for the pipeline according to the preferred environment sequence. +6. Click **Create**. + +## Edit a continuous deployment pipeline + +### Prerequisites + +- To edit a continuous deployment pipeline in an organization, you must have the `ENVIRONMENT-MANAGEMENT` permission. By default, `ENVIRONMENT-MANAGEMENT` permission is granted to Admin, Choreo Platform Engineer and Choreo DevOps roles. + +To edit a pipeline, follow the steps given below: + +1. Sign in to [Choreo](https://console.choreo.dev/). +2. In the Choreo Console, go to the top navigation menu and click **Organization**. Then select your organization. +3. In the left navigation menu, click **DevOps** and then click **CD Pipelines**. +4. Click the edit icon corresponding to the pipeline you want to edit. +5. Update the pipeline name, mark the pipeline as default, and change the sequence of environments. +6. Click **Update**. + + +## Delete a continuous deployment pipeline + +To delete a pipeline, follow the steps given below: + +!!! warning + Continuous deployment pipeline deletion is a permanent, non-reversible operation. + +!!! info "Note" + The **default** continuous deployment pipeline of the organization cannot be deleted. + +1. Sign in to [Choreo](https://console.choreo.dev/). +2. In the Choreo Console, go to the top navigation menu and click **Organization**. Then select your organization. +3. In the left navigation menu, click **DevOps** and then click **CD Pipelines**. +4. Click the delete icon corresponding to the pipeline you want to delete. This displays a confirmation dialog with details on the impact of deletion. + + !!! info "Note" + If the pipeline is utilized by one or more projects, deletion will not be permitted. To proceed with deleting such a pipeline, you must first remove it from every project that is currently using it. + +5. Review the details, then type the pipeline name to confirm the deletion. +6. Click **Delete**. + + +## Add a continuous deployment pipeline to a project + +### Prerequisites + +- To add a continuous deployment pipeline to a project, you must have the `ENVIRONMENT-MANAGEMENT` or `PROJECT-MANAGEMENT` permission. By default, `ENVIRONMENT-MANAGEMENT` permission is granted to Admin, Choreo Platform Engineer and Choreo DevOps roles and `PROJECT-MANAGEMENT` permission is granted to Admin, Choreo DevOps, and Project Admin roles. + +To add a pipeline to a project, follow the steps given below: + +1. Sign in to [Choreo](https://console.choreo.dev/). +2. In the Choreo Console, go to the top navigation menu and click **Organization**. Then select your organization. +3. Click the project you want to add the pipeline. +4. In the left navigation menu, click **DevOps** and then click **CD Pipelines**. +5. Click **+ Add** and select the pipelines you want to add to the project. +6. Click **Add**. + + +## Remove a continuous deployment pipeline from a project + +### Prerequisites + +- To remove a continuous deployment pipeline from a project, you must have the `ENVIRONMENT-MANAGEMENT` or `PROJECT-MANAGEMENT` permission. By default, `ENVIRONMENT-MANAGEMENT` permission is granted to Admin, Choreo Platform Engineer and Choreo DevOps roles and `PROJECT-MANAGEMENT` permission is granted to Admin, Choreo DevOps, and Project Admin roles. + +To remove a pipeline from a project, follow the steps given below: + +1. Sign in to [Choreo](https://console.choreo.dev/). +2. In the Choreo Console, go to the top navigation menu and click **Organization**. Then select your organization. +3. Click the project you want to remove the pipeline. +4. In the left navigation menu, click **DevOps** and then click **CD Pipelines**. +5. Click **Remove** corresponding to the pipeline you want to remove from the project. This displays a confirmation dialog with details on the impact of deletion. +6. Review the details, then type the pipeline name to confirm the deletion. +7. Click **Remove**. + +## Change default continuous deployment pipeline of a project + +### Prerequisites + +- To change the default continuous deployment pipeline of a project, you must have the `ENVIRONMENT-MANAGEMENT` or `PROJECT-MANAGEMENT` permission. By default, `ENVIRONMENT-MANAGEMENT` permission is granted to Admin, Choreo Platform Engineer and Choreo DevOps roles and `PROJECT-MANAGEMENT` permission is granted to Admin, Choreo DevOps, and Project Admin roles. + +To change the default pipeline of a project, follow the steps given below: + +1. Sign in to [Choreo](https://console.choreo.dev/). +2. In the Choreo Console, go to the top navigation menu and click **Organization**. Then select your organization. +3. Click the project you want to change the default pipeline. +4. In the left navigation menu, click **DevOps** and then click **CD Pipelines**. +5. Click **Set as Default** corresponding to the pipeline you want to set as the default pipeline for the project. This displays a confirmation dialog that details the impact of setting the new pipeline as the project default. +6. Click **Confirm**. + + !!! info "Note" + The **default** continuous deployment pipeline is configured separately at both the organization and project levels. When a project is created, it inherits the organization's **default** pipeline. The project's **default** pipeline then defines the default promotion order for its components on the Deploy page. diff --git a/en/pe-docs/docs/devops/ci-pipelines/ci-pipeline-logs.md b/en/pe-docs/docs/devops/ci-pipelines/ci-pipeline-logs.md new file mode 100644 index 000000000..32171677c --- /dev/null +++ b/en/pe-docs/docs/devops/ci-pipelines/ci-pipeline-logs.md @@ -0,0 +1,26 @@ +# CI Pipeline Logs + +The CI pipeline logs in Choreo offer detailed insights into the build process of your components. These logs are divided into three main sections: + +1. **Initialization** + +This section captures logs related to setting up the environment for the build process. During this stage, the [component.yaml](https://wso2.com/choreo/docs/develop-components/manage-component-source-configurations/#overview-of-the-componentyaml-file) file is validated to ensure it meets the necessary requirements. + +2. **Build** + +This step involves the actual build process. Here, you can view logs specific to your component's build. Additionally, a Trivy vulnerability scan is performed to identify any potential vulnerabilities in the built image. + +3. **Finalization** + +This section includes logs related to the final steps of the build process. It involves cleaning up the build environment, marking the completion of the build. + +To view the build pipeline logs, follow these steps: + +1. Sign in to the [Choreo Console](https://console.choreo.dev/). +2. In the Choreo Console, select the appropriate **Organization**, **Project**, and **Component** from the top navigation menu. + +!!! info "Note" + Build pipeline logs are accessible only at the component level. + +3. In the left navigation menu, click on **DevOps** and then click on **CI Pipelines** to view a list of builds for the selected component. +4. Click on the **View Details** button corresponding to the build you wish to inspect. This will display the detailed logs for that specific build. diff --git a/en/pe-docs/docs/devops/ci-pipelines/configure-ci-pipeline.md b/en/pe-docs/docs/devops/ci-pipelines/configure-ci-pipeline.md new file mode 100644 index 000000000..0c1e0bfd9 --- /dev/null +++ b/en/pe-docs/docs/devops/ci-pipelines/configure-ci-pipeline.md @@ -0,0 +1,64 @@ +# Configure CI Pipeline + +Choreo has built in CI pipeline so that the developers and platform engineers do not need to worry about creating docker images and saving in a container registry on their own. The developers could visit the build page from their component view and then build the component so that it would be ready for the deployment. As a platform engineer you may need to enforce configurations on this build pipeline. Each component would have its own build page, and you configure them separately. + +More Information can be found in [CI-CD concept](../../choreo-concepts/ci-cd.md) document. + +## Trigger a Build + +You can trigger a build from past commit or the latest commit. + +1. In the Choreo Console top navigation menu, select the **Organization**, then the **Project** and finally the relevant **Component**. +2. In the left navigation menu, click **DevOps** and then click **CI Pipelines**. +3. On the **CI Pipelines** page, click **Build Latest**. + + !!! note + The build process may take some time. You can track progress in the **Build Details** pane. Once complete, the build status changes to **Success**. + + +Alternatively, you can pick a specific commit and trigger a build too. Click on **Show Commits**. Select the commit you want to build and Click **Build**. + +Another option you have is to build from a tag. Click on the down arrow next to **Show Commits** button. Then from the dropdown menu, select **Show Tags**. Click on **Show Tags** button.Finally, select the tag you want to pick and Click **Build**. + +!!! note + Users can trigger builds using specific tags from the connected Git repository. However, this action bypasses the standard branch-based deployment process and should only be used for critical, time-sensitive scenarios, as it can disrupt deployment track integrity. + +To configure build pipeline, click **Build Configurations**. The configurations would be specific to the type of component. For certain components, you can configure build time environment variables too. + + +### Repeatable builds + +Choreo can replicate builds from an identical code version (Git commit). This means that multiple builds initiated from the same Git commit will generate Docker images with the same behavior. + +## Build logs + +To view Build Logs for a component, + +1. In the Choreo Console top navigation menu, select the **Organization**, then the **Project** and finally the relevant **Component**. +2. In the left navigation menu, click **DevOps** and then click **CI Pipelines**. +3. You can view build logs for specific builds on the **CI Pipelines** page. +4. To view details of a specific build, click **View Details** corresponding to the build. + + +## Auto Build on Commit + +With Auto Build on Commit, you can configure the build pipeline to be triggered once a new commit is available in the repository's selected branch. + +1. In the Choreo Console top navigation menu, select the **Organization**, then the **Project** list and finally the relevant **Component**. +2. In the left navigation menu, click **DevOps** and then click **CI Pipelines**. +3. On the **CI Pipelines** page, toggle **Auto Build on Commit** radio button. + + !!! info + If the developer created a component by providing an opensource repository without authorizing Github, you would see a button **Configure Auto Build** instead of **Auto Build on Commit** radio button. Click **Configure Auto Build**. Then it would redirect to github login page and ask to authorize **WSO2 Cloud App**. Once you authorize, you would be redirected back to same page. Now you would see a button **Add Repository** instead of **Configure Auto Build**. Click on **Add Repository**. It would redirect to github again asking to install and authorize WSO2 Cloud App for provided set of repositories. You can pick the repositories you would like to authorize and finally click **Install and Authorize**. After that, **Auto Build on Commit** radio button would appear. + + + + +## Configure CI Pipeline Variables and Secrets. + +Choreo supports adding and updating configurations like environment variables and secrets related to your CI Pipeline. To apply such configurations to the CI pipeline of a component, + +1. In the Choreo Console top navigation menu, select the **Organization**, then the **Project** and finally the relevant **Component**. +2. In the left navigation menu, click **DevOps** and then click **CI Pipelines**. +3. On the **CI Pipelines** page, click **Build Variables and Secrets**. +4. In the slide-in window appears in right, you can add or edit environment variables. diff --git a/en/pe-docs/docs/devops/ci-pipelines/integrate-unit-tests-into-the-build-pipeline.md b/en/pe-docs/docs/devops/ci-pipelines/integrate-unit-tests-into-the-build-pipeline.md new file mode 100644 index 000000000..4fb0c717c --- /dev/null +++ b/en/pe-docs/docs/devops/ci-pipelines/integrate-unit-tests-into-the-build-pipeline.md @@ -0,0 +1,35 @@ +# Integrate Unit Tests into the Choreo CI Pipeline + +Choreo allows you to integrate unit tests into the CI pipeline, enabling code validation before deployment. This ensures early testing of code changes, reducing the risk of defects in production. + +!!! note + Currently, Choreo supports unit tests only for the `WSO2 MI` buildpack. + +## How it works + +### Step 1: Write tests + +You can create unit tests in your source code using standard testing libraries. For step-by-step instructions on creating unit tests for WSO2 Micro Integrator projects, see [Creating a Unit Test Suite](https://mi.docs.wso2.com/en/latest/develop/creating-unit-test-suite/). + +### Step 2: Enable unit tests + +1. Sign in to the [Choreo Console](https://console.choreo.dev/). +2. In the Choreo Console top navigation menu, select the **Organization**, then the **Project** and finally the relevant **Component**. +3. In the left navigation menu, click **DevOps** and then click **CI Pipelines**. +4. Click on **Build Configurations** to edit the build configurations. +5. Turn on the **Unit Test** toggle. +6. Click **Save**. + +### Step 3: Trigger a new build + +- On the **CI Pipelines** page, click **Build Latest**. + +This starts a new build with unit tests enabled. You can monitor its progress in the **Build Details** pane. + +## View failed unit tests + +If a unit test fails during the build, you can view its detailed logs for troubleshooting. Click **View Details** corresponding to the failed build, then expand the failed unit test step to view the logs. + +## Explore a sample + +To see unit tests in action within the build pipeline, try out the [WSO2 MI helloworld](https://github.com/wso2/choreo-samples/tree/main/hello-world-mi) sample. diff --git a/en/pe-docs/docs/devops/manage-configuration-groups.md b/en/pe-docs/docs/devops/manage-configuration-groups.md new file mode 100644 index 000000000..dc05678da --- /dev/null +++ b/en/pe-docs/docs/devops/manage-configuration-groups.md @@ -0,0 +1,111 @@ + +# Manage Configuration Groups + +Choreo allows you to create Configuration Groups to efficiently manage reusable configurations across components within your organization. A Configuration Group is a collection of key-value pairs, where values can be defined for multiple environments. This feature ensures consistency and simplifies the management of configurations across environments. + +Configuration groups can be defined at organization level and link to components at deployment time. Once linked, Choreo automatically resolves and mounts the configurations to the respective environments on deployment. You can either link a configuration group to inject the configurations as environment variables or file mounts. + +!!!important + - All configuration group values are encrypted and stored in environment-specific key vaults. + - Management of configuration groups is restricted to users with Choreo Admin, DevOps, and Platform Engineer roles. + - Developers can discover configuration groups available within the organization via the **Choreo Internal Marketplace**. + +## Create a configuration group + +To create a new configuration group, follow the steps given below: + +1. In the [Choreo Console](https://console.choreo.dev/), go to the top navigation menu. Click **Organization** and select your organization. +2. In the left navigation menu, click **DevOps** and then click **Configuration Groups**. +3. On the **Configuration Groups** page, click **Create** and specify the following details to create a new configuration group: + + - **Name**: A name for the configuration group (Unique within the organization). + - **Description**: A description for the configuration group (Optional). + - **Define Keys**: Define the keys for the configuration group. + + - Configuration keys uniquely identify values in a configuration group. You can map these keys to environment variables or file mounts during deployment. Each key must be unique within the group. + + - **Assign Values**: Define values by environment for the keys defined. + + - By default, all the environments are grouped together allowing you to manage configuration smoothly. You can separate and manage configuration values for each environment as needed. + + - **Create**: Click **Create** to create the configuration group. + +4. Now you can link this configuration group to any component within the organization. + +!!!note + - Configuration groups created will be listed in the **Choreo Internal Marketplace**, improving visibility and discoverability for developers. + - All configuration groups will also be listed in the component deployment drawers, allowing developers to easily link them during deployment. + +## Link and use configuration groups + +The configuration groups created at organization level can be linked to any component within the organization. A configuration group can be linked as **Environment Variables** or **File Mounts** at deployment time. + +Linking a configuration group will inject the values defined in the group during deployment. The values are mapped to environment variable names or file names based on the keys defined in the configuration group. If needed, you can customize the environment variable name or file name by updating the mapping at deployment. + +To link a configuration group to a component, follow the steps given below: + +1. Navigate to the component you want to link the configuration group using top navigation menu. +2. On the left navigation menu, click **DevOps** and click **CD Pipelines**. +3. Click **Configure & Deploy**, this will open the configuration and deployment wizard. +3. In the wizard, link the configuration groups as **Environment Variables** or **File Mounts**, based on your requirements. + + === "Environment Variables" + + - Choose the configuration group you want to link to the component. + - Click **Link** to link the configuration group to the component. + + === "File Mounts" + + - Choose the configuration group you want to link to the component. + - Specify the **Mount Path** to mount the configuration files. + + !!!note + All configurations within the selected configuration group will be mounted as individual files to the specified mount path/directory. + + - Click **Link** to link the configuration group to the component. + +4. Complete the deployment wizard by providing the required details and click **Deploy** to deploy the component with the updated configurations. + +## View & edit a configuration group + +To view & edit a configuration group, follow the steps given below: + +1. In the [Choreo Console](https://console.choreo.dev/), go to the top navigation menu. Click **Organization** and select your organization. +2. In the left navigation menu, click **DevOps** and then click **Configuration Groups**. +3. In the **Configuration Groups** list, select the desired configuration group to view. + + !!!note + - Only non-sensitive configuration values are displayed in the view mode. + - Updating the configuration group will not affect the current deployment; changes will be applied when the component is redeployed. + +### Edit the configuration group + +Configuration keys and values within a configuration group can be modified, and these changes will take effect when the components using the configuration group are redeployed. + +To edit the configuration group definition, click **Edit the Configuration Group** and make the necessary updates: + +- Add or remove configuration keys. +- Update the configuration group's display name and description. + +To edit the configuration values, click the edit icon in the corresponding set of environments and modify the required details: + +- Update configuration values. +- Add a new set of configuration values. +- Add or remove environments from an existing set. + +!!! warning + - **Adding a new environment:** Non-sensitive configuration values will be copied to the new environment, but sensitive values will not be. As a result, sensitive values will be cleared across all environments in the set. **New values must be provided for sensitive configurations.** + - **Removing an environment:** All configuration values for the removed environment will be deleted. + +## Delete a configuration group + +To delete a configuration group, follow the steps given below: + +!!! warning + Deleting a configuration group is a permanent, non-reversible action. Ensure that the configuration group is not linked to any component before deleting it. + +1. In the [Choreo Console](https://console.choreo.dev/), go to the top navigation menu. Click **Organization** and select your organization. +2. In the left navigation menu, click **DevOps** and then click **Configuration Groups**. +3. In the **Configuration Groups** list, click the delete icon next to the configuration group you want to delete. This will display a confirmation dialog with details about the impact of the deletion. +4. Review the details, then type the configuration group name to confirm the deletion. +5. Click **Delete**. diff --git a/en/pe-docs/docs/governance/approvals/review-workflow-approval-requests.md b/en/pe-docs/docs/governance/approvals/review-workflow-approval-requests.md new file mode 100644 index 000000000..352cced29 --- /dev/null +++ b/en/pe-docs/docs/governance/approvals/review-workflow-approval-requests.md @@ -0,0 +1,36 @@ +# Review Workflow Approval Requests + +In Choreo, Platform Engineers can [configure approvals for workflows](../workflows/configure-approvals-for-choreo-workflows.md) and assign specific users as approvers. + +!!! note + - You must have **Approve Component Promotion Requests** permission under **WORKFLOW-MANAGEMENT** permission group to approve component promotion requests. + - You must have **Approve API Subscriptions** permission under **WORKFLOW-MANAGEMENT** Permission group to approve subscription requests. + +If you are assigned as an authorized reviewer for a particular workflow approval request, you will receive an email notification when a request is submitted for approval. The email includes a summary of the request and a link to the **Approvals** page in the Choreo Console, where you can review the details and either approve or reject the request. + +!!! note + - Workflow approvals are managed at the project level. If a role with the necessary permissions is assigned in a project context, only members of the user group bound to that role within the specific project will receive notifications for requests made in that project. For example, if you are assigned the Project Admin role (which includes the necessary permissions) for project A, you will only be notified of workflow requests within project A. + - Users with organization-level permissions will receive notifications for all workflow requests across any project in the organization. + +Other approvers within your organization will also receive notifications for workflow requests and may review a request before you. If a request has already been reviewed, it will appear under the **Past** tab on the **Approvals** page. + +Approval requests are submitted on behalf of the team. Once approved, any authorized team member can execute the task. For certain tasks, execution may occur automatically upon approval. + +## View workflow approval requests + +To view workflow approval requests assigned to you, follow these steps: + +1. Sign in to the [Choreo Console](https://console.choreo.dev/). +2. In the Choreo Console header, go to the **Organization** list and select your organization. +3. In the left navigation menu, click **Governance** and then click **Approvals**. +4. This opens the **Approvals** page where you can see all approval requests assigned to you. The **Pending** tab lists requests that are yet to be reviewed. The **Past** tab displays requests already reviewed by you or other approvers, as well as requests canceled by the requester. +4. To view details of a specific request, click **Review** corresponding to it. + +## Approve or reject an approval request + +To approve or reject a request, follow these steps: + +1. Follow the instructions in the [View workflow approval requests](#view-workflow-approval-requests) section above to see details of the workflow you want to review. + Alternatively, click the Choreo Console link in the approval request email notification you received. This takes you to the request details in the Choreo Console. +2. Review the request and click **Approve** or **Reject** based on your decision. + diff --git a/en/pe-docs/docs/governance/egress-control/control-egress-traffic-for-your-organization.md b/en/pe-docs/docs/governance/egress-control/control-egress-traffic-for-your-organization.md new file mode 100644 index 000000000..91086fed1 --- /dev/null +++ b/en/pe-docs/docs/governance/egress-control/control-egress-traffic-for-your-organization.md @@ -0,0 +1,41 @@ +# Control Egress Traffic for Your Organization + +In Choreo, you can manage egress traffic originating from your applications by setting up an allow list or deny list. By default, egress traffic is allowed to any destination unless specifically restricted. + +## Configure an egress policy at the organization level + +To configure an egress policy at the organization level, follow these steps: + +1. Sign in to the [Choreo Console](https://console.choreo.dev/). +2. In the Choreo Console header, go to the **Organization** list and select your organization. +3. In the left navigation menu, click **Governance**, then click **Egress Control**. +4. Click **+ Create** to add a new egress policy +5. Select the type of egress control to apply and add the required rules: + + - **Allow All**: Allows all egress traffic by default. You can selectively block traffic to specific IP ranges. + - **Deny All**: Blocks all egress traffic by default. You can selectively allow traffic to specific IP ranges or domains. + + !!! note + + - Once you select an egress control type and create a rule, you cannot change the type. To change the type, you must delete existing rules. + - Egress rules you add can disrupt your application if they block traffic to required destinations. Ensure you add rules appropriately to prevent such disruptions. + - If you use the **Deny All** type, be sure to add Choreo-managed database hosts to the allowed list. + - Egress policies apply across all environments in an organization. + - Egress policies do not apply to API proxies. + + +## Override the organization-level egress policy at the project level + +An egress policy set at the project level can override the organization-level policy, depending on the egress control type you select. + +To override the organization-level egress policy at the project level, follow these steps: + +1. Sign in to the [Choreo Console](https://console.choreo.dev/). +2. In the Choreo Console header, go to the **Project** list and select your project. +3. In the left navigation menu, click **Governance**, then click **Egress Control**. +4. You will see that the organization-level egress policy is enforced by default. +5. Add required project-level rules to further restrict egress traffic. + + - If the **Allow All** egress control type is selected at the organization level, you can add project-level deny rules to further restrict traffic. + - If the **Deny All** egress control type is selected at the organization level, you can remove allow rules inherited from the organization level to further restrict traffic. + diff --git a/en/pe-docs/docs/governance/workflows/configure-approvals-for-choreo-workflows.md b/en/pe-docs/docs/governance/workflows/configure-approvals-for-choreo-workflows.md new file mode 100644 index 000000000..b9d25d14f --- /dev/null +++ b/en/pe-docs/docs/governance/workflows/configure-approvals-for-choreo-workflows.md @@ -0,0 +1,61 @@ +# Configure Approvals for Choreo Workflows + +Choreo allows you to configure approval processes for specific workflows within the platform. An approval process for a workflow ensures that critical or sensitive changes are properly managed and controlled. + +Choreo currently allows you to configure approvals for environment promotion and API subscription workflows. + +Configuring approvals for environment promotion allows authorized users to control components being promoted to a critical/production environment. + +Configuring approvals for the API subscription workflow allows you to create subscription plans that require approval before being activated. This feature allows you to control access to APIs by requiring administrative review and authorization of subscriptions before they become active. + +## Permissions to review and respond to approval requests + +Click the respective tab for details on permissions depending on the workflow for which you want to configure approvals: + +=== "Environment promotion" + + To review and respond to environment promotion approval requests, a user must have the following permissions. Platform engineers must ensure that users designated to review and respond to approval requests have these permissions: + + - **WORKFLOW-MANAGEMENT**: + - Approve component promotion requests: Grants access to review and approve the promotion of components to critical environments. + - **PROJECT-MANAGEMENT**: Grants access to view and approve workflow requests. This is the same permission used to update or delete projects. + +=== "API subscription" + + To review and respond to API subscription approval requests, a user must have the following permissions. Platform engineers must ensure that users designated to review and respond to approval requests have these permissions: + + - **WORKFLOW-MANAGEMENT**: + - Approve API subscriptions: Grants access to review and approve API subscription workflow requests. + - **PROJECT-MANAGEMENT**: + Grants access to view and approve workflow requests. This is the same permission used to update or delete projects. + +## Set up an approval process for a workflow + +To set up an approval process for a workflow, follow these steps: + +!!! note + - Platform engineers can designate specific roles and assignees to review and respond to requests associated with each workflow. + +1. Sign in to the [Choreo Console](https://console.choreo.dev/). +2. In the Choreo Console header, go to the **Organization** list and select your organization. +3. In the left navigation menu, click **Governance** and then click **Workflows**. +4. Click the edit icon corresponding to the workflow for which you want to configure an approval. +5. In the **Configure Workflow** dialog that opens, select roles and assignees to review and respond to workflow approval requests. + + - In the **Roles** field, select one or more roles depending on your preference. Any user assigned to these roles can review and respond to requests. + - In the **Assignees** field, select specific users who can review and approve workflow requests. Assignees can be any Choreo user, even if they are not assigned to a selected role. + + !!! info "Important" + Currently, there is no validation to ensure that the specified roles and assignees have the necessary permissions to review and respond to requests. If the [required permissions](#permissions-to-review-and-respond-to-approval-requests) are not correctly configured, some users may receive email notifications but will be unable to review the requests. + +6. Click **Save**. This configures and enables the approval process for the workflow. + +Once you enable the approval process for a workflow, see the following details on how to submit a request for approval and the approval process. Click the respective tab depending on the workflow for which you enabled the approval process: + +=== "Environment promotion" + + Once you configure an approval process for environment promotion, developers must submit a request for approval to use the workflow. An authorized assignee must then [review and approve the request](../approvals/review-workflow-approval-requests.md) for a developer to proceed with the task related to the workflow. + +=== "API subscription" + + Once you configure an approval process for API subscription, platform engineers can select the **Approval required** checkbox to create or update subscription plans to require approval. API consumers using these plans must request approval to proceed. An authorized approver must then [review and approve the request](../approvals/review-workflow-approval-requests.md) before the subscription is granted. diff --git a/en/pe-docs/docs/index.md b/en/pe-docs/docs/index.md new file mode 100755 index 000000000..55887eaa5 --- /dev/null +++ b/en/pe-docs/docs/index.md @@ -0,0 +1,18 @@ +--- +template: templates/pe-home-page.html +--- + +
+
+
+

Welcome to the Choreo Learning Portal

+
+
+

Note
The Home page will be designed to provide a guided experience to any user coming to docs with a valid Choreo use case.
We intend to ONLY INCLUDE conceptual information in the documentation for the relevant topics and **NOT INCLUDE** any how to guides, or instructions with the exception of Tutorials.

+
+
+ +
+
+
+ diff --git a/en/pe-docs/docs/infrastructure/configure-vpns-on-the-choreo-cloud-data-plane.md b/en/pe-docs/docs/infrastructure/configure-vpns-on-the-choreo-cloud-data-plane.md new file mode 100644 index 000000000..a1c284689 --- /dev/null +++ b/en/pe-docs/docs/infrastructure/configure-vpns-on-the-choreo-cloud-data-plane.md @@ -0,0 +1,193 @@ +# Configure VPNs on the Choreo Cloud Data Plane + +Secure access to private networks from the Choreo cloud data plane is an essential use case for cloud data plane users. + +Choreo allows this secure connection using [Tailscale](https://tailscale.com/). For this, Choreo provides a prebuilt Tailscale image component that can act as a forward proxy, which you can deploy in your Choreo project as a service. This service allows you to forward traffic to your external networks via Tailscale’s peer-to-peer [WireGuard](https://tailscale.com/kb/1035/wireguard) network. + +The following diagram illustrates the high-level deployment architecture of the Tailscale pre-installed forward proxy: + +![Deployment architecture](../assets/img/devops-and-ci-cd/tailscale/deployment-architecture.png) + +Let's take a look at the specifics of each part to understand the deployment architecture. + +- **Choreo project** + + In Choreo, a project groups various components. For more information on what a project in Choreo is, see the documentation on [Project](../choreo-concepts/project.md). + +- **Tailscale proxy** + + This acts as the Tailscale pre-installed forward proxy, facilitating secure peer-to-peer WireGuard connections from the Choreo cloud data plane to private networks. It includes a [Tailscale Daemon](https://tailscale.com/kb/1278/tailscaled), [SOCKS5 proxy](https://tailscale.com/kb/1112/userspace-networking#socks5-vs-http), and a configurable TCP forwarder. + + - **Tailscale daemon** + + This is the core component of Tailscale. It is a software service that provides secure network connectivity and private networking solutions. For more details see the [Tailscale documentation](https://tailscale.com/kb/1278/tailscaled). + + - **SOCKS5 proxy** + + This uses Tailscale’s [userspace networking](https://tailscale.com/kb/1112/userspace-networking) mode, rather than the kernel mode. Therefore, the inbuilt SOCKS5 proxy handles the forwarded traffic and directs it through the Tailscale network. + + - **TCP forwarder** + + Forwards inbound TCP (transmission control protocol) traffic from the Tailscale proxy container’s network interface to the SOCKS5 proxy, ensuring it reaches its destination via the secured WireGuard tunnel. + +- **User applications and the Choreo API gateway** + + User applications within the same namespace (project) can use the Kubernetes service created to front the Tailscale proxy, for connecting to the corresponding private endpoints. You can either expose this service within the organization via the internal API gateway or expose it to the public via the external API gateway. + +
+ +Now that you understand the deployment architecture, let’s explore how you can use Tailscale to secure connections to your private networks. + +## Configure and use Tailscale to access private network endpoints + +This section walks you through the steps to create, configure, deploy, and use the Tailscale proxy component. + +![Tailscale proxy deployment](../assets/img/devops-and-ci-cd/tailscale/tailscale-proxy-deployment.png) + +Let's get started. + +### Prerequisites + +- Understand the basics of [how Tailscale works](https://tailscale.com/blog/how-tailscale-works). +- Have a Tailscale account (Tailnet). There are multiple plans available for you to set up your Tailscale network. For details, see [Tailscale plans](https://tailscale.com/pricing). +- Install Tailscale and connect your private data center or server to it, so that your private services are accessible via your Tailscale network. To quickly get started with Tailscale, see the [Tailscale quickstart](https://tailscale.com/kb/1017/install). + +### Step 1: Create the Tailscale proxy component + +!!! Note - + Component creation is not available for the **Platform Engineer** role. Switch to the **Developer** perspective to create a component. + +1. Sign in to the [Choreo Console](https://console.choreo.dev/). +2. In the Choreo Console top navigation menu, select the **Organization**, and then the **Project**. +3. On the project home page, click **+ Create**, and select the **Service** card to create a service component. +4. Click the **Container Registry** from the **Connect a Docker Image** section +5. In the **Container Registry** list, select **Choreo Samples Registry**. +6. Click the **Tailscale Proxy** card. +7. Enter a display name, component name, and a description for the service. For this guide, let's enter the following values: + + |Field | Value | + |----------------------|--------------------------| + |Component Display Name| Tailscale proxy | + |Component Name | tailscale-proxy | + |Description | Tailscale proxy component| + +8. Click **Create**. + +Now you have successfully created the Tailscale proxy. You can proceed to configure and deploy it. + +### Step 2: Configure and deploy the Tailscale proxy + +Here, you will add the required volume mounts, set the Tailscale authentication key, configure the TCP forwarder, configure endpoints, and deploy the Tailscale proxy. Follow the steps given below: + +#### Step 2.1: Add required volume mounts + +Tailscale requires the following volume mounts for its operations: + + - `/var/run/tailscale` + - `/.local` + +To create the volume mounts, follow the step-by-step instructions in [Configure Storage](../k8s-operations/storage/configure-storage.md). + +#### Step 2.2: Configure and deploy the component + +To configure and deploy the component, follow the steps given below: + +1. In the left navigation menu, click **CI Pipelines**. +2. On the **Setup** card, click **Configure & Deploy**. +3. In the **Environment Configurations** pane that opens, click **+ Add** and add the `TS_AUTH_KEY` environment variable as a secret. To add the environment variable, you must obtain an authentication key from your Tailscale network. For details on how to obtain an authentication key from your Tailscale network, see [Auth keys](https://tailscale.com/kb/1085/auth-keys) in the Tailscale documentation. + + !!! info "Note" + The authentication keys obtained from your Tailscale network have an expiration date and require periodic rotation. To avoid manual rotation, you can generate non-expiring authentication keys using OAuth clients. For details, see [Generating long-lived auth keys](https://tailscale.com/kb/1215/oauth-clients#generating-long-lived-auth-keys) in the Tailscale documentation. + + Follow these steps if you want to add an OAuth client secret to the Tailscale proxy component instead of the `TS_AUTH_KEY` environment variable as a secret: + + 1. Define a tag named `choreo-vpn` in your Tailscale ACLs. For details, see [Define a tag](https://tailscale.com/kb/1068/tags#define-a-tag) in the Tailscale documentation. + 2. Create an [OAuth client](https://tailscale.com/kb/1215/oauth-clients) with the following scope, ensuring it is assigned to the `choreo-vpn` tag: + - Keys → Auth Keys → write + 3. Generate the OAuth client and copy the client secret. + 4. Set the client secret as an environment variable named `OAUTH_CLIENT_SECRET`. + +4. Click **Next**. +5. In the **File Mount** pane that opens, click **+ Add**. +6. To mount a configuration file to the Tailscale proxy component and specify the port mapping for the TCP forward proxy running there, do the following: + 1. Specify `/config.yaml` as the **Mount Path**. + 2. Specify the following in the sample configuration file: + ``` + portMappings: + 8080: "100.108.78.93:8090" + 8081: "100.108.78.93:1433" + ``` + !!! note + In this sample configuration, the TCP traffic arriving at port 8080 on your Tailscale proxy will be forwarded to port 8090 on the node with IP address 100.108.78.93 in your Tailscale network. Similarly, port 8081 will map to the corresponding address. You can find the IP addresses of your nodes on the [Tailscale machines](https://login.tailscale.com/admin/machines) page in your Tailscale network's admin console or via the Tailscale clients running on your machine. +7. Click **Next**. +8. In the **Endpoints** pane that opens, click **+ Add** and edit the `endpoints.yaml` configuration to expose your Tailscale proxy as a service. The following is a sample `endpoints.yaml` configuration you can use: + +!!! note + The sample `endpoints.yaml` file given below defines two project-level endpoints. These endpoints can be used by other components within the same project to access the services. If you want to directly expose your private endpoint via the Choreo gateway either with the **Public** or **Organization** visibility, you can set the `networkVisibility` property of the endpoint to `Public` or `Organization`. + ``` yaml + version: 0.1 + endpoints: + - name: Private HTTP service + port: 8080 + type: REST + networkVisibility: Project + context: / + - name: Private DB service + port: 8081 + type: TCP + networkVisibility: Project + context: / + ``` +9. Click **Save**. +10. Click **Next** and then click **Deploy**. + +!!! note + Deploying the component may take a while. You can track the progress by observing the logs. Once the deployment is complete, the build status changes to **Active** on the **Development** environment card. +When the component is deployed, you can observe a new node connected to your Tailscale network. To view this, go to the [Tailscale machines](https://login.tailscale.com/admin/machines) page of your Tailscale coordination server. + +### Step 3: Access private network endpoints with the Tailscale proxy +Now you have successfully deployed the Tailscale proxy in your project and it is connected to your Tailnet. You can proceed to use the Tailscale proxy to provision access for other components to securely access private network endpoints. +You can [configure endpoints](https://wso2.com/choreo/docs/develop-components/configure-endpoints/#learn-the-endpointsyaml-file) of the Tailscale proxy to use it for various aspects within Choreo. + +## Post-deployment actions + +### Handle node key expiry + +Tailscale nodes have a default [node key](https://tailscale.com/kb/1010/node-keys) expiry time of 180 days. Nodes require re-authentication after key expiry to avoid connection losses and application downtime. There is an option to disable node key expiry if necessary. For more details, see [Node key expiry documentation](https://tailscale.com/kb/1028/key-expiry). + +### Handle auth key expiry + +[Auth keys](https://tailscale.com/kb/1085/auth-keys) are used to register new nodes into your Tailscale network. The default [expiry time for auth keys](https://tailscale.com/kb/1085/auth-keys#key-expiry) is 90 days, but nodes remain connected even after auth key expiry. This becomes an issue only if the Tailscale Proxy component is redeployed or restarted. + +### Update port mapping configurations + +If you want to add a new private endpoint to your network and access it via the same Tailscale proxy within Choreo, you must add a new port mapping entry in the port mapping configuration of your Tailscale proxy deployment. + +## Best practices + +### Configure health checks + +Since the Tailscale proxy acts as a forward proxy, it is important to configure health checks. You can use one of the open ports of the TCP forwarder as a health endpoint. For details on how to set up health probes in Choreo, see [Set up health checks](../k8s-operations/set-up-health-checks.md). + +### Use Tailscale ACLs + +You can use [Tailscale ACLs](https://tailscale.com/kb/1018/acls) to precisely manage permission for users and devices on your Tailnet. + +### Disable scale-to-zero for the Tailscale proxy + +It is recommended to disable [Scale-to-Zero](../k8s-operations/scaling/autoscale-components-with-scale-to-zero.md) for the Tailscale proxy because it acts as a forward proxy and should always be up and running to make consistent connections with the Tailscale VPN mesh. +If you enable Scale-to-Zero, you may experience service downtime. + +### Run multiple replicas with HPA (horizontal pod autoscaler) + +To achieve high availability and resiliency for the Tailscale proxy, you must run multiple replicas with HPA. To configure multiple replicas for the Tailscale proxy component, go to the **Scaling** page under **DevOps**. For more details, see [Autoscale component replicas](../k8s-operations/scaling/autoscale-component-replicas.md) + +## Security best practices + +Before deploying the Tailscale proxy in production environments, it is recommended to follow the Tailscale [production best practices](https://tailscale.com/kb/1300/production-best-practices) and [security best practices](https://tailscale.com/kb/1196/security-hardening). +!!! Note + Choreo blocks incoming connections from other nodes in your Tailnet to the Tailscale proxy to prevent access to your project’s namespace in the Choreo cloud data plane. + +## Troubleshoot issues + +For assistance in resolving common Tailscale proxy issues, see [Troubleshoot Tailscale proxy issues](../references/troubleshoot-choreo.md#troubleshoot-tailscale-proxy-issues). \ No newline at end of file diff --git a/en/pe-docs/docs/infrastructure/credentials/set-up-git-provider-authentication-for-choreo-deployments.md b/en/pe-docs/docs/infrastructure/credentials/set-up-git-provider-authentication-for-choreo-deployments.md new file mode 100644 index 000000000..06e65256b --- /dev/null +++ b/en/pe-docs/docs/infrastructure/credentials/set-up-git-provider-authentication-for-choreo-deployments.md @@ -0,0 +1,51 @@ +# Set Up Git Provider Authentication for Choreo Deployments + +Choreo enables you to develop components by connecting your GitHub, Bitbucket, or GitLab repository. You have the flexibility to either connect an existing repository or start with an empty repository and commit the source code later. By integrating your repositories with Choreo, you can automate tasks and optimize workflows across multiple systems, all within the Choreo platform. Choreo currently supports GitHub, Bitbucket, and GitLab as Git providers. + +!!! tip + Choreo supports both Bitbucket Server and Bitbucket Cloud. The currently supported Bitbucket Server version is 8.9.2. + +In Choreo, you can connect a Git repository that contains some source code or a Docker project. Once you connect your Git repository to Choreo, you can build, deploy, and manage your application easily with choreo-console. + +## Connect a Git repository to Choreo + +You can connect Bitbucket, Gitlab repositories to choreo organization using a Personal Access Token(PAT). For github, the developers can install [WSO2 Cloud App](https://github.com/marketplace/choreo-apps) during component creation and get necessary permissions via Github itself. + +1. Sign in to the [Choreo Console](https://console.choreo.dev/). +2. In the Choreo Console header, go to the **Organization** list and select your organization. +3. In the left navigation menu, click **Infrastructure** and then click **Credentials**. +5. Under **Git Credentials** tab, click **+Import Credentials** to configure the Git repository connection. +6. Enter a **Credential Name**, select the Git provider, and enter the **Personal Access Token** you obtained from the Git provider. +7. Click **Save**. + +## Authorize GitHub with Choreo + +Authorizing Choreo as a GitHub application grants Choreo the following permissions to perform the respective actions on your behalf within the repository: + +|Permission | Read| Write| Description | +|-------------|-----|------|-----------------------------------------------------------------------| +|Issues | Y | N | Read component ID label to filter the pull requests | +|Metadata | Y | N | List repositories | +|Contents | Y | Y | List branches and create a branch to commit sample code | +|Pull Request | Y | Y | Create a pull request if you start with a Choreo sample | +|Webhooks | Y | Y | Trigger automatic deployment and configuration generation | + + +## Authorize Bitbucket with Choreo + +Authorizing using a personal access token (PAT) from Bitbucket grants Choreo the following permissions to perform the respective actions on your behalf within the repository. + +|Permission | Read| Write| Description | +|--------------|-----|------|--------------------------------------------------------------------| +|Account | Y | N | Get user information and workspace details | +|Repositories | Y | Y | List branches and create a branch to commit sample code | +|Pull Requests | Y | Y | Create a pull request if you start with a Choreo sample | +|Webhooks | Y | Y | Trigger automatic deployment and configuration generation | + +## Authorize self-managed GitLab with Choreo + +Authorizing using a personal access token (PAT) obtained from your GitLab self-managed server grants Choreo the following permissions to perform the respective actions on your behalf within the repository. + +|Permission | Description | +|--------------|-------------------------------------------------------------------------------------| +|API | Grants full read/write access to the API, covering all groups and projects, as well as read/write access to the repository.| diff --git a/en/pe-docs/docs/infrastructure/credentials/use-your-own-container-registry.md b/en/pe-docs/docs/infrastructure/credentials/use-your-own-container-registry.md new file mode 100644 index 000000000..8a6817ae3 --- /dev/null +++ b/en/pe-docs/docs/infrastructure/credentials/use-your-own-container-registry.md @@ -0,0 +1,160 @@ +# Use Your Own Container Registry + +Choreo allows you to deploy and manage prebuilt container images from external container registries as Choreo components. This enables you to deploy and effectively manage your container images within the Choreo environment. + +!!! info + This feature is currently only available on [private data planes (PDPs)](../../choreo-concepts/data-planes.md#private-data-planes) for the following component types: + + - Service + - Web Application + - Scheduled Task + - Manual Task + +## Prerequisites + +Before you try out this guide, ensure you have the following: + +- **A container registry**: Ensure you have a container registry containing the images you want to deploy. Choreo is compatible with various container registries, including but not limited to GCR (Google Container Registry), ACR (Azure Container Registry), GitHub Container Registry, and Docker Hub. + +- **(Optional) An external build/CI pipeline**: This is to initiate automatic deployments during the build process outside of Choreo. + +When using a container registry to deploy a component, Choreo cannot create an image from the source code (Git) or initiate a new deployment when a new image is ready. However, you can use your existing build process to trigger a deployment on Choreo by sending an HTTP POST request to a webhook with the new image details. + +This feature is currently only available on private data planes (PDPs). + +## Register a container registry + +To get started, establish a connection between your container registry and Choreo. + +!!! info + When you use your Choreo credentials, Choreo does not _pull_ your images into its control plane. Instead, it functions as an orchestrator, facilitating your data plane's ability to retrieve images from an external container registry. Choreo passes on these credentials to the data plane for authentication and access. + +To register your container registry, follow these steps: + +1. Sign in to the [Choreo Console](https://console.choreo.dev/). +2. In the Choreo Console header, go to the **Organization** list and select your organization. +3. In the left navigation menu, click **Infrastructure** and then click **Credentials**. +4. Click the **Container Registries** tab. +5. Click **+Add Registry** to configure the Git repository connection. +6. Specify a **Registry Display Name**. +7. Select the **Authentication Type**. Fill in the required information depending on your authentication type. For details on each authentication type, see [Authentication types](#authentication-types). +8. Click **Save**. + +### Authentication types + +Choreo provides the following authentication options: + +#### Public (anonymous) access + +You can use this option to establish a connection with a container registry that permits unrestricted public or anonymous access (for example, Public Docker Hub). In this case, only the registry host information is necessary. + +For example, the following are the Docker Hub registry hosts for reference: + +| Vendor | Registry host | +| --------------------------------- | ------------------------- | +| Docker Hub (public repositories) | `registry.hub.docker.com` | +| Docker Hub (private repositories) | `registry.docker.com` | + +\* If necessary, you can use other mirrors instead of the above. + +#### Basic authentication + +To use basic authentication to authenticate to the container registry, you must provide the username and password. + +#### Docker config + +You can provide a Docker config in JSON format to authenticate to the container registry. This option only allows you to register one container registry. That is, it **only allows a single registry under `auths`**. + +You must provide the credentials directly within the configuration. Choreo cannot utilize references to executable authentication plugins. + +Sample Docker config format: + +```json +{ + "auths": { + "index.docker.io/v1/": { + "auth": "c3R...zE2" + } + } +} +``` + +#### Vendor-specific authentication + +This option is specifically for private data planes, where your cloud provider manages authentication at the Kubernetes level. Choreo requires knowledge of the registry host because the data plane already possesses implicit (preconfigured) access to the registry. + +Follow the guidelines below based on your container registry: + +=== "ACR" +**Azure Container Registry** + + Recommended authentication options: + + * [**Service principal-based basic authentication**](https://learn.microsoft.com/en-us/azure/container-registry/container-registry-auth-service-principal) + + * **Vendor-specific authentication on Azure private data planes** + + Contact Choreo support to enable infrastructure-level private access to your registry from your Azure private data plane on AKS. If you are on a self-managed PDP on Azure, follow [this guide](https://learn.microsoft.com/en-us/azure/aks/cluster-container-registry-integration?toc=%2Fazure%2Fcontainer-registry%2Ftoc.json&bc=%2Fazure%2Fcontainer-registry%2Fbreadcrumb%2Ftoc.json&tabs=azure-cli). + +=== "GAR" +**Google Artifact Registry** + + Recommended authentication options: + + * [**Service account-based basic authentication**](https://cloud.google.com/artifact-registry/docs/docker/pushing-and-pulling#key) + + Use the service account key in JSON format ([`_json_key`](https://cloud.google.com/artifact-registry/docs/docker/authentication#:~:text=of%20the%20following%3A-,_json_key,-if%20you%20are)) as the username and specify the minified JSON contents of the service account key as the password. + + You can use `jq` as follows to minify the service account JSON key file: + + `jq -c . ` + + * **Vendor-specific authentication on GCP private data planes** + + Contact Choreo support to enable infrastructure-level private access to your registry from your GCP private data plane on GKE. If you are on a self-managed PDP on GCP, see [https://cloud.google.com/artifact-registry/docs/access-control#grant-project](https://cloud.google.com/artifact-registry/docs/access-control#grant-project). + +=== "AWS ECR" +**Elastic Container Registry** + + ECR does not allow the creation of static access passwords for basic authentication. The passwords (that is, access tokens) provided by AWS are only valid for 10 hours and must be manually regenerated. However, when an ECR is attached to an EKS cluster at an infrastructure level, this limitation does not apply because the authentication is handled by AWS internally. For details, see [https://docs.aws.amazon.com/AmazonECR/latest/userguide/registry_auth.html](https://docs.aws.amazon.com/AmazonECR/latest/userguide/registry_auth.html). + + Choreo recommends using ECR when you are exclusively on an AWS private data plane using the vendor-specific authentication option. Contact Choreo support to enable a private connection between your ECR and the underlying EKS clusters on your data plane. If you are on a self-managed PDP, you can follow [this guide](https://docs.aws.amazon.com/AmazonECR/latest/userguide/ECR_on_EKS.html). + +=== "Docker Hub (Private)" + + Recommended authentication options: + + * **Basic authentication** + + Use your Docker Hub username/password or an access token. You can generate an access token from your Docker Hub account settings and use it in place of the password. For details, see [https://docs.docker.com/docker-hub/access-tokens/](https://docs.docker.com/docker-hub/access-tokens/). + + * **Docker config** + + Sign in to the Docker CLI and copy the contents of the docker config JSON. Note that external credential stores and multiple repositories within the same config object are not supported. For more information, see [https://docs.docker.com/engine/reference/commandline/login/](https://docs.docker.com/engine/reference/commandline/login/). + +=== "GHCR" +**GitHub Container Registry** + + Recommended authentication option: + + * **Basic authentication using a PAT token** + + Create a personal access token (PAT) and use it in place of the password. You cannot use your own GitHub password. You must provide a [PAT token](https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-container-registry#authenticating-with-a-personal-access-token-classicn). + + +## Auto-deploy images in Choreo with an external CI/build pipeline + +Choreo does not have automatic detection and deployment for newly added images or tags in the linked container registry. To overcome this limitation, Choreo allows you to integrate your own CI pipelines and initiate deployments manually. This approach enables you to use your existing CI setup or build a pipeline for image creation and pushing. You can then trigger automatic deployments using a webhook. + +Follow the steps below to configure your CI/build pipeline: + +1. Build and push the container image associated with a Choreo component to your container registry. +2. In the Choreo Console top navigation menu, select the **Organization**, then the **Project**, and finally the relevant **Component**. +3. In the left navigation menu, click **DevOps** and then click **External CI**. +4. Generate a token for your CI pipeline from the **Manage Tokens** section. + +!!! note - + - The tokens are bound to a specific component. + - It is recommended to reference the token from a secure location available to your CI pipeline. For example, use a GitHub secret if you are using GitHub Actions. + +5. To trigger an automatic deployment to your development environment, you can initiate an HTTP POST request to the Choreo webhook endpoint with the updated image details. Alternatively, you can use the provided Webhook snippets. This action will seamlessly deploy the image to the development environment. diff --git a/en/pe-docs/docs/infrastructure/dataplanes/data-planes.md b/en/pe-docs/docs/infrastructure/dataplanes/data-planes.md new file mode 100644 index 000000000..a871ab42d --- /dev/null +++ b/en/pe-docs/docs/infrastructure/dataplanes/data-planes.md @@ -0,0 +1,22 @@ +# Data planes + +The data plane in Choreo is the runtime environment where user applications are deployed based on configurations defined in the control plane. It supports a variety of applications, including services, web apps, APIs, integrations, and scheduled tasks, and allows for a polyglot approach with multiple programming languages. All runtime traffic is securely contained within the data plane, ensuring user data remains isolated and protected. + +See [Data planes concept](../../choreo-concepts/data-planes.md) for more information on Choreo's data plane architecture. + +## Types of data planes + +Choreo offers two types of data planes: + +1. **Choreo cloud data plane**: A public data plane managed by Choreo. This cloud data plane is shared across multiple organizations but provides a secure and scalable environment for deploying applications. +2. **Private data plane**: A data plane that you can deploy and manage within your own infrastructure. Private data planes are compatible with major cloud providers like Azure, AWS, and GCP, as well as on-premises infrastructure. + +## Set up a data plane + +By default, when you create an organization in Choreo, a cloud data plane is automatically assigned to you. During the organization onboarding process, you can select a region for the cloud data plane. Free users are limited to creating projects in the chosen region, while paid users can create projects across multiple regions. + +If you wish to set up a private data plane, you can reach out to the Choreo team for assistance. They will guide you through the setup process based on your specific requirements. For more information on the management models available for private data planes, refer to the [Private Data Plane Management Models](../../references/private-data-plane-management-models.md) documentation. + +## Self Service Data Plane Management + +Choreo is currently developing self-service data plane management capabilities for private data planes. This feature will enable you to create, manage, and monitor private data planes independently. Keep an eye out for updates on this upcoming functionality. diff --git a/en/pe-docs/docs/infrastructure/domains/configure-a-custom-domain-for-your-organization.md b/en/pe-docs/docs/infrastructure/domains/configure-a-custom-domain-for-your-organization.md new file mode 100644 index 000000000..13b978998 --- /dev/null +++ b/en/pe-docs/docs/infrastructure/domains/configure-a-custom-domain-for-your-organization.md @@ -0,0 +1,154 @@ + +# Configure a Custom Domain for Your Organization + +A custom domain is essential for effective branding, discoverability, and credibility of a website. Choreo allows you to easily configure custom domains for your organization, enabling developers to utilize it to configure custom URLs for their components such as API proxies, services, web applications, and webhooks. + +This section provides an overview of Choreo’s custom domain configuration model and guides you through configuring a custom domain for your organization. + +## Choreo custom domain configuration model + +Choreo allows platform engineers to add custom domains for their organizations. When an platform engineer adds custom domains to an organization, component developers can submit requests to utilize the custom domains for their respective components. These requests require approval from platform engineers. Upon approval, the custom domain and the relevant URL customization become available to the component. + +## Configure a custom domain for an organization + +To add a custom domain for your organization, follow the steps given below: + +!!! info "Note" + To add a custom domain, you must have **Manage Custom Domains** permission under **URL Management** permission group. + +1. Sign in to the [Choreo Console](https://console.choreo.dev/). +2. In the top navigation menu, click the **Organization** list and select your organization. +3. In the left navigation menu, click **Infrastructure** and then click **Domains**. +4. Click the **Active Domains** tab. +5. Click **+ Add Domains**. +6. In the **Add a Custom Domain** pane, do the following: + + 1. Enter your domain name. + 2. Select the environment to apply the domain name. + 3. Select the entity type to apply the domain name. + + !!! tip + In this context: + + - The **API** entity type represents Choreo components exposed via an endpoint, including API Proxy, Service, and Webhook components. + - The **Web App** entity type represents the Web Application component. + +7. Take a look at the generated CNAME target value displayed and create a DNS record associating the domain name to the CNAME target value with your DNS provider. + + ![CNAME target value](../../assets/img/administer/configure-domain/cname-target-value.png) + + !!! info + When you select **Developer Portal** as the type, the environment is not applicable, and the CNAME alias will be displayed as follows: + ![Developer Portal CNAME target value](../../assets/img/administer/configure-domain/developer-portal-cname-target-value.png) + +8. Once the CNAME type DNS record is created, click **Verify**. + + !!! info "Note" + If the CNAME mapping is correct, the verification completes successfully. It can take some time for the configured CNAME mapping to be globally available. + +9. On successful verification of the custom domain, click **Next**. +10. Select a TLS certificate provider depending on your preference. You can either import the TLS certificates you created for the custom domain or click **Let's Encrypt** to allow Choreo to generate and manage the certificates for you. + + + !!! note "If you want to import your own certificate, it should adhere to specific guidelines" + - TLS certificate guidelines: + - It should be issued by a certificate authority (CA) and should contain the domain's public key along with additional information such as the domain name, the company that owns the domain, the certificate's expiration date, and the digital signature of the issuing CA. + - It should be an X509 certificate. + - It should be in the PEM format. + - It should be issued directly or through a wildcard entry for the provided custom URL. For example, + - For direct issuance, the SSL file must include the exact domain name. For example, if the domain is `apis.choreo.dev`, the SSL file must include `apis.choreo.com`. + - For wildcard entries, the SSL file should use a wildcard notation to cover all subdomains under the provided URL. For example, if the CNAME is `apis.choreo.dev`, the SSL file should use `*.choreo.dev`. + - TLS key file guidelines: + - It should be in the PEM format. + - It must be encrypted using RSA encryption. + - Certificate chain file guidelines: + - The chain file, which is essential for some clients to verify the authenticity of a server's SSL/TLS certificate, should contain your domain's SSL/TLS certificate (optional, as this can be provided via the certificate itself) and one or more intermediate certificates in the correct order, leading back to a root certificate. + - All certificates in the chain should be X509 certificates in PEM format. +
For step-by-step instructions on constructing a certificate chain with a root certificate, click here + To construct a certificate chain with a root certificate, you must organize and combine the certificates in the correct sequence. A typical certificate chain consists of the following: + - **Root certificate**: The trusted self-signed certificate issued by the certificate authority (CA). + - **Intermediate certificates** (if any): Certificates issued by the root CA to subordinate CAs. + - **Leaf certificate**: Your end-entity certificate issued by the CA. This is an optional certificate that may be included within the chain or provided separately.

+ Follow these steps to construct the certificate chain: + 1. Obtain and organize your certificates in the correct order: + - **Leaf certificate**: The public certificate issued by the CA. This is optional and may be included within the chain or provided separately. + - **Intermediate certificates**: Obtain these from the CA, if applicable. + - **Root certificate**: Obtain this from the CA. If it is self-signed, it serves as the trust anchor. + 2. Combine the certificates into a single file in the following order: + - Leaf certificate: This is your public certificate issued by the CA. + - Intermediate certificates if applicable: Include these in the correct hierarchical order. + - Root certificate: Include this at the end of the file.

+ Use a text editor or a command-line tool to concatenate the certificates into one file, ensuring each certificate begins and ends with the proper markers. Also make sure the `BEGIN CERTIFICATE` and `END CERTIFICATE` markers appear on a new line: + ``` + -----BEGIN CERTIFICATE----- + + -----END CERTIFICATE----- + -----BEGIN CERTIFICATE----- + + -----END CERTIFICATE----- + -----BEGIN CERTIFICATE----- + + -----END CERTIFICATE----- + ``` + 3. Save the concatenated file. You can save it with a name such as `certificate_chain.pem`. + 4. Use the following command to verify that your certificate chain is constructed correctly: + ``` + openssl verify -CAfile .pem certificate_chain.pem + ``` + Replace `.pem` with the path to your root certificate or a bundle containing both the root and intermediate certificates. + 5. Once the certificate chain is verified, upload it via the Choreo Console: + ![Upload certificate chain](../../assets/img/administer/configure-domain/upload-certificate-chain.png) + - If the constructed chain includes the leaf certificate, follow these steps: + - Upload the constructed certificate chain in the **TLS Certificate** field. + - Upload the private key file in the **TLS Key File** field. + - Do not upload a certificate chain file, as it is already included in the TLS certificate. + - If the constructed chain does not include the leaf certificate, follow these steps: + - Upload the leaf certificate in the **TLS Certificate** field. + - Upload the private key file in the **TLS Key File** field. + - Upload the constructed certificate chain in the **Certificate Chain File** field. + + To proceed with this step in this guide, click **Let's Encrypt**. + +11. To save the custom domain, click **Add**. + +Now, you have successfully added a custom domain for your organization. + +You can see the added custom domain listed in the **Active Domains** tab under the URL **Settings** tab. + +![Active domains](../../assets/img/administer/configure-domain/active-domains.png) + +The custom domain you added will be available to the entity types in the specified environment. You can request the custom domain when configuring a custom URL for a component. + +!!! info "Note" + If you add a custom domain for the **Developer Portal** type, the customization is applied immediately, and you can access the organization’s Developer Portal via the added domain. + +If you want to view the entity types that use a particular custom domain, click the specific custom domain listed in the **Active Domains** tab. + +## Configure a custom URL for a component + +When an platform engineer adds custom domains for specific environments, developers can request any available custom domain to configure a custom URL for a component in a specific environment. + + +## Approve a custom URL request + +When a developer requests a custom URL, the request will be listed in the organization-level **Domains** page under the **Pending URL Requests** tab. + +To approve a custom URL mapping, follow the steps given below: + +!!! info "Note" + To approve custom URL requests, you must have **Approve URL Mappings** permission under **URL Management** permission group. + + +1. Sign in to the [Choreo Console](https://console.choreo.dev/). +2. In the top navigation menu, click the **Organization** list and select your organization. +3. In the left navigation menu, click **Infrastructure** and then click **Domains**. +4. Click the **Pending URL Requests** tab. You will see all the pending URL mapping requests sent by developers. + ![Pending URL requests](../../assets/img/administer/configure-domain/pending-url-requests.png) +5. Go to the custom URL you want to approve and click the corresponding **Approve URL Mapping** icon under the **Action** column. +6. Review the details and click **Approve**. + + Once approved, the invoke URL of the component gets replaced with the configured custom URL. + + ![Custom URL](../../assets/img/administer/configure-domain/custom-url.png) + + Now you have successfully utilized the configured custom domain to set up a custom URL for a component. diff --git a/en/pe-docs/docs/infrastructure/environments/manage-environments.md b/en/pe-docs/docs/infrastructure/environments/manage-environments.md new file mode 100644 index 000000000..8a340a93a --- /dev/null +++ b/en/pe-docs/docs/infrastructure/environments/manage-environments.md @@ -0,0 +1,47 @@ +# Manage Environments + +By default, all projects created in the cloud data planes (irrespective of the data plane region) are provisioned with two environments (i.e., development and production). + +The environments are listed in the order of deployment and promotion. The initial deployment takes place in the first environment and you can proceed to promote a component to subsequent environments. + +## Create a new environment + +### Prerequisites + +- To create a new environment in a private data plane organization, you must have the `ENVIRONMENT-MANAGEMENT` permission. By default, `ENVIRONMENT-MANAGEMENT` permission is granted to Admin, Choreo Platform Engineer and Choreo DevOps roles. + +To create a new environment, follow the steps given below: + +1. Sign in to [Choreo](https://console.choreo.dev/). +2. In the Choreo Console, go to the top navigation menu and click **Organization**. Then select your organization. +3. In the left navigation menu, click **Infrastructure** and then click **Environments**. +4. On the **Environments** page, click **Create** and specify the following details to create a new environment: + + - **Name**: A display name for the new environment. + - **Data Plane** - The data plane to create the new environment. + + - **Name**: A display name for the new environment. + - **Data Plane** - The data plane to create the new environment. + +!!!tip + The **Data Plane** list displays all the private data planes registered under your organization along with **consumed** Choreo cloud data planes. + + - **DNS Prefix**: A DNS prefix to identify the exposed APIs in the environment. Here, the base domain depends on the custom domain attached to the API gateways provisioned on the selected data plane. + - **Mark environment as a Production environment**: Select if you want this environment to be a production environment. + +!!!tip + In Choreo, you can have multiple non-production and production environments. To work in a production environment, you must have privileged permissions to access and deploy to production environments. + +## Delete an environment + +To delete an environment, follow the steps given below: + +!!! warning + Environment deletion is a permanent, non-reversible operation. + +1. Sign in to [Choreo](https://console.choreo.dev/). +2. In the Choreo Console, go to the top navigation menu and click **Organization**. Then select your organization. +3. In the left navigation menu, click **Infrastructure** and then click **Environments**. +4. In the **Environments** list, click the delete icon corresponding to the environment you want to delete. This displays a confirmation dialog with details on the impact of deletion. +5. Review the details, then type the environment name to confirm the deletion. +6. Click **Delete**. diff --git a/en/pe-docs/docs/insights/cost-optimization.md b/en/pe-docs/docs/insights/cost-optimization.md new file mode 100644 index 000000000..325b4e61e --- /dev/null +++ b/en/pe-docs/docs/insights/cost-optimization.md @@ -0,0 +1,190 @@ +# Choreo Cost Optimization + +## Overview + +The Choreo cost optimization feature provides detailed cost insights across your organization, enabling you to analyze resource utilization and cost efficiency at the Organization, Project, and Component levels. The dashboards provide comprehensive visualizations and actionable recommendations to optimize cloud infrastructure costs while maintaining performance. + +**All metrics, visualizations, and analytics displayed across the Organization, Project, and Component levels reflect data for the current month, from the first day up to the current date.** This provides you with up-to-date insights into your resource utilization and cost efficiency. +Monthly figures show the accumulated data for the current month so far, while comparisons to previous month are also available in some metrics. This approach gives you both immediate visibility into current spending patterns and understanding the trend compared to last month for optimization decisions. + +You can use this information to track ongoing cost optimization efforts and make timely adjustments to your resource allocations within the current billing cycle. + +## Organization Level + +![Organization level dashboard](../assets/img/cost-optimization/OrganizationLevel.png) + +At the Organization level, Choreo provides key insights into overall cost savings and resource efficiency across all your projects. You can view the following metrics and visualizations: + +* **Monthly Savings Summary** + + Monthly savings summary chart + + + This chart visualizes the percentage of cost savings achieved (by manual or automatic application of recommendations) compared to missed savings (potential savings missed due to recommendations not being applied) up to the current date. You should aim to maximize the saved cost and minimize missed savings. + +* **Total Monthly Savings** + + Total monthly savings card + + + This card shows the cost saved in the current month through manual or automatic application of recommendations. It includes a breakdown for Production and Non-Production environments, with a dropdown showing savings for each respective environment. + +* **Monthly Missed Savings** + + Monthly missed savings card + + This card displays the potential cost savings that were missed due to the failure to apply recommendations, whether manually or automatically. It provides a breakdown of these missed savings for both production and non-production environments, listing values for each individual environment. It is recommended to keep these missed savings as minimal as possible. + +* **Annual Savings** + + Annual savings card + + This card shows accumulated savings throughout the year. It combines the savings completed through the end of the previous month with savings achieved up to the present day of the current month. This demonstrates that a fully cost-optimized organization with no savings for the current month has achieved this state by saving costs in previous months. + +* **Monthly CPU and Memory Cost** + + Monthly CPU and Memory cost card + + This card shows the cost incurred for CPU and Memory allocation across all components in your organization. It includes a percentage change compared to the previous month to indicate cost trends. + +* **Estimated Monthly Cost** + + Estimated monthly cost card + + This card shows the forecasted cost at the end of the month, with an environmental breakdown, regardless of which day of the month you view it. + +* **Monthly CPU and Memory Efficiency** + + Monthly CPU and Memory efficiency card + + This card shows the percentage utilization of CPU and Memory compared to allocation. This metric indicates your resource optimization level, which directly reflects cost optimization. The breakdown of CPU and Memory efficiencies provides individual understanding of each resource's optimization. The percentage change shown compares current efficiency to last month's efficiency with an arrow indicating increase or decrease. + +* **Cost Analysis Plot** + + Cost analysis plot + + The plot consists of three lines: + + * **Allocation Cost** - The maximum of Request Cost and Utilization Cost at a given point in time. This is what you're billed for CPU and memory resource costs. + * **Utilization Cost** - The ideal cost that should be billed if no extra resources were allocated. This is typically not achievable in practice as some buffer is needed for uninterrupted service. + * **Optimized Cost** - The cost suggested by the optimization algorithm that provides sufficient buffer for efficient performance while optimizing costs. + + You can filter the view to show All resources, CPU only, or Memory only for time-based cost analysis. + +* **Cost Savings (Deployments Summary)** + + Deployments summary cards + + Under the Cost Savings section, these cards provide a summary of all deployments in your organization: + + * **Under Provisioned Deployments** - Number of deployments with insufficient resource allocation + * **Over Provisioned Deployments** - Number of deployments with over-allocated resources + * **Idle Deployments** - Deployments with no traffic for the last 3 days + * **Auto-optimized deployments** - Number of deployments with auto-optimization enabled + * **Deployments that require attention** - Number of deployments with auto-optimization disabled that have recommendations for manual application + * **Total number of deployments** - Number of active deployments + +* **Cost Savings (Project Summary)** + + Project summary table + + This table under the Cost Savings section includes a summary of all projects in your organization. Each row represents a project with columns showing: + * Saved Cost after applying recommendations automatically/manually + * Actual Cost after Savings + * CPU and Memory Efficiency + * Ratio of Applied Suggestions to total available recommendations + + You can click on any project in this table or use the top navigation to visit the Project Level cost insights. + +## Project Level + +![Project level dashboard](../assets/img/cost-optimization/ProjectLevel.png) + +The Project Level view is similar to the Organization Level, with all monthly metrics focused on the selected project. The charts, cards, plots, and tables follow the same format as the Organization Level. + +An additional feature at this level is the ability to toggle auto-apply for each component in the Cost Savings (Component Summary) table, or for all components. This simplifies the process of enabling auto-application of recommendations across all components in a project. + + Deployments summary cards + + +These toggles enable automatic application of recommendations for all deployments in the selected components. + +## Component Level + +![Component level dashboard](../assets/img/cost-optimization/ComponentLevel.png) + +The Component Level differs from both Organization and Project levels. At the Component Level, you can access the release level through both deployment track (version) and environment configuration as shown: + + Release selection + +At the Release Level within the Component Level, you can view: + +* **Component details and Optimization Configurations** + + Component details card + + This card shows configuration data for the deployment, including number of replicas, scale to zero settings, and horizontal pod auto-scaling that can be configured in DevOps. + +#### Optimization Configurations + Under the Optimization Configurations section, you can configure how Choreo applies cost optimization recommendations: + + Auto Apply Recommendations: + + When enabled, this toggle automatically implements resource right-sizing recommendations daily. Every 24 hours the system automatically checks if the release has any recommendations that would save more than $0.01, and if found, applies them without requiring manual intervention. This feature helps maintain continuous cost efficiency without constant monitoring. + + + Safety Buffer: + + This setting determines how conservatively the optimization algorithm calculates resource recommendations: + + Low: Adds a 10% buffer above the calculated resource requirements, which maximizes cost savings but provides less headroom for unexpected traffic spikes + + High: Adds a 20% buffer above the calculated resource requirements, offering more capacity for handling unexpected load increases - recommended for production environments + + + + The Safety Buffer setting helps you balance between maximum cost efficiency and maintaining reliable performance. For mission-critical applications or services with variable workloads, the High setting provides additional capacity to handle sudden traffic increases, while the Low setting is suitable for predictable workloads where you want to optimize costs more aggressively. + These configurations allow you to tailor the optimization behavior to your specific needs, balancing cost-saving opportunities with operational requirements at the component level. + +* **Monthly Cost, Missed Savings, Efficiency and Estimated Cost** + + Component metrics cards + + These cards summarize the cost and resource metrics similar to those at the Organization and Project levels. + +* **CPU Metrics Analysis** + + CPU metrics chart + +* **Memory Metrics Analysis** + + Memory metrics chart + +* **Recommendations** + + Memory metrics chart + + The system provides **automated** and **manual** recommendations for cost reduction. + +### Optimization Types + +* **Resource Right-Sizing** + * Suggests optimized CPU and memory limits + * Provides potential cost savings per adjustment + +* **Enable Scale to Zero** + * Stops a component when no requests are being served + * Reduces idle infrastructure costs + +* **Stop Deployment** + * Identifies and halts unused deployments + * Prevents unnecessary spending on unused resources + +### Applying Recommendations + +* **Manually Apply**: You can review and apply suggestions individually +* **Auto-Apply Toggle**: Enables automatic cost optimizations for projects/components + +## Conclusion + +The Choreo Cost Optimization feature helps you improve cloud resource efficiency by providing insights and recommendations at various levels. With interactive visualizations, automated recommendations, and optimization tracking, you can reduce infrastructure costs while maintaining performance. diff --git a/en/pe-docs/docs/insights/delivery-insights/configure-delivery-insights.md b/en/pe-docs/docs/insights/delivery-insights/configure-delivery-insights.md new file mode 100644 index 000000000..ef812a926 --- /dev/null +++ b/en/pe-docs/docs/insights/delivery-insights/configure-delivery-insights.md @@ -0,0 +1,96 @@ +# Delivery Insights + +![Delivery insights dashboard](../../assets/img/monitoring-and-insights/engineering-insights/delivery-insights-dashboard.png){.cInlineImage-full} + +You can view delivery insights in Choreo to use as Key Performer Indicators (KPIs) to measure your organization's DevOps team's performance. Choreo enables this feature by default for all organizations. Delivery insights includes the following four key metrics (DORA metrics) that are regarded as the most important metrics to indicate team performance: + +- Deployment Frequency: How often an organization successfully releases to production +- Lead Time for Changes: The amount of time it takes a commit to get into production +- Change Failure Rate: The percentage of deployments causing a failure in production +- Mean Time to Recovery: How long it takes an organization to recover from a failure in production + + +Choreo enables two insights by default; deployment frequency and lead time for change. + +## Configure the Delivery Insights dashboard with all metrics + +To configure the dashboard by enabling the other two metrics, follow the steps below: + +1. Sign in to [Choreo](https://console.choreo.dev/). +2. In the Choreo Console, go to the top navigation menu and click **Organization**. Then select your organization. +3. On the left navigation menu, click **Insights** and then click on **Delivery**. +4. Scroll to the bottom of the dashboard and click **Configure**. +5. Select your incident management system. Currently, Choreo only supports GitHub. + +## Configuring GitHub as the incident management system + +![Configure](../../assets/img/monitoring-and-insights/engineering-insights/enable-dora-metrics.png){.cInlineImage-full} + +To configure GitHub as the incident management system, follow the steps below: + +### Step 1: Authorize + +![Authorize](../../assets/img/monitoring-and-insights/engineering-insights/add-integration-cio-dashboard.png){.cInlineImage-threeQuarter} + +First, let's authorize Choreo to access the repositories used to record incidents. + +On the **Add Integration** page, select **GitHub** and click **Authorize with GitHub**. + +Once the authorization process is complete, you can start configuring the GitHub repository. + +### Step 2: Configure + +![Configure](../../assets/img/monitoring-and-insights/engineering-insights/add-integration-configure.png){.cInlineImage-threeQuarter} + +By default, Choreo collects incident details(issues) from all repositories containing Choreo components. However, you can configure a GitHub account and a GitHub repository to allow Choreo to read issues from a specific repository, and then click **Next**. + +| **Field** | **Description** | **Value** | +|-----------------|-----------------------------|-----------------------------| +| **Data Plane** | Choreo collects incident details by running a scheduled job which invokes the GitHub API periodically. This job runs on the user's data plane. This configuration allows users to specify a preferred data plane to run the job, especially when they have multiple data planes. | Select a preferred data plane from the **Data Plane** list. | +| **GitHub Account** | The GitHub account you have your repositories in. | Select your GitHub account that includes the repository used for incident collection.| +| **GitHub Repository**| By default, Choreo will collect incident details(issues) from all repositories that already have Choreo components. | + + +### Step 3: Filter label + +![Filter Label](../../assets/img/monitoring-and-insights/engineering-insights/filter-label.png){.cInlineImage-threeQuarter} + +The filter label allows Choreo to scrape issues associated with that label. + +- **Incident Label**: The label Choreo uses to identify incidents. For example, `Type/Incident`. + +- **Invalid incident label**(Optional): Choreo will not scrape issues with this label and will proceed to skip these issues. For example, `Resolution/Invalid`. You can use this label when you want to ignore issues. For example, closing an issue after identifying that it doesn't qualify as an incident issue as it was due to a user error. + +Once you configure the labels, click **Save**. + +Choreo will enable incident data publishing in the background once you save. Once completed, the metric charts will appear in the delivery insights dashboard for **Mean Time To Recover** and **Change Failure Rate**. If there are any issues in the configuration, the configure banner will reappear, and the user can proceed to reconfigure. + +### Step 4: Enrich incident tickets with deployment information + +Choreo extracts deployment information from the relevant incident and generates DORA metrics that help you analyze the deployment statistics related to the incidents. Therefore, you must manually update the GitHub issue with the relevant deployment-related information. Follow the steps below to add the deployment information to the GitHub issue. + +#### Get deployment details + +1. In the Choreo Console top navigation menu, select the **Organization**, then the **Project** and finally the relevant **Component** for which the incident was reported. +2. On the left navigation menu, click **DevOps** and then click on **CD Pipelines** +3. On the **Production Environment** card, click **Deployment History**. +4. On the right-hand side panel, select the relevant deployment, and click **Release details** to copy the deployment details to the clipboard. + + ![Copy to clipboard](../../assets/img/monitoring-and-insights/engineering-insights/deployment-copy-to-clipboard.png){.cInlineImage-small} + +#### Add deployment information to the GitHub issue + +1. Edit the GitHub issue to add the deployment information. +2. Paste the deployment information you copied (in step 4 under the section `Get deployment details`) at the end of the issue body. +3. Click **Save**. + +That's it! You have successfully configured your delivery insights dashboard to include all DORA metrics. + +!!! note + The delivery insights dashboard is expected to reflect the latest statistics within approximately 30 minutes. + +## Edit configurations + + ![Edit configurations](../../assets/img/monitoring-and-insights/engineering-insights/edit-configurations.png) + + You can edit or override the configurations you made via the edit option in the dashboard. diff --git a/en/pe-docs/docs/insights/delivery-insights/view-delivery-insights.md b/en/pe-docs/docs/insights/delivery-insights/view-delivery-insights.md new file mode 100644 index 000000000..3b46bd9cb --- /dev/null +++ b/en/pe-docs/docs/insights/delivery-insights/view-delivery-insights.md @@ -0,0 +1,110 @@ +# View Delivery Insights + +The Choreo delivery insights dashboard offers a detailed overview of DevOps team efficiency through DORA metrics, which consist of four core performance indicators. Here’s how Choreo visualizes these metrics: each is presented with a concise summary and illustrated dynamically through charts or graphs to highlight trends and insights. + +### Snapshot view + +![DORA metric summary](../../assets/img/monitoring-and-insights/engineering-insights/dora-metrics-summary.png){.cInlineImage-full} + +The snapshot view includes four tiles on the top of the dashboard, summarizing DORA metrics for the entire time period you select. The snapshot view categorizes each metric into four performance levels: elite, high, medium, and low. The categorization is based on the 2020 DORA metric report. + +![DORA matrix](../../assets/img/monitoring-and-insights/engineering-insights/dora-matrix.png){.cInlineImage-threeQuarter} + +### Time series view + +The time series view provides a graphical representation of how the statistics have changed over a period of time. You can use this view to analyze team performance and identify trends. + +![Time Series View](../../assets/img/monitoring-and-insights/engineering-insights/time-series-view.jpg){.cInlineImage-full} + + +## Deployment frequency + +DORA team definition: The frequency at which an organization successfully releases to production. + +In Choreo, this translates to the number of times an organization deploys a component to the production environment. Choreo does not count the deployment done to the development or other lower environments. + +### Snapshot view + +![Deployment Frequency Snapshot](../../assets/img/monitoring-and-insights/engineering-insights/deployment-frequency-snapshot.png){.cInlineImage-small} + +The snapshot view of the `Deployment Frequency` metric shows the deployment frequency for all components within the selected organization. The frequency is dynamically determined and rounded to the nearest measurement. For example, if there is more than one deployment daily, the deployment frequency is measured in `deployments per day`. If the deployment frequency is less, it is measured in a higher granularity. For example, `deployments per week`. + +A lower deployment frequency indicates that your organizational efficiency is low and that you need to evaluate and improve the processes to encourage frequent releases. + +Choreo also displays the total number of deployments for the selected time range and the percentage increase or decrease compared to the previous time range. + +### Time series view + +![Deployment Frequency time series view](../../assets/img/monitoring-and-insights/engineering-insights/deployment-frequency-time-series.png){.cInlineImage-half} + +The time series view for the `Deployment Frequency` metric visualizes the deployment count as a bar chart for the selected time period. Deployment count is aggregated based on the ‘view by’ selector. Hovering over each bar shows the counts for the aggregated period. +Using this chart, organizations can identify deployment patterns, such as days of the week/months of the year where more deployments are likely to happen (near quarterly release days) and periods with fewer deployments. Decision-makers can then take steps to investigate and improve performance. +This chart displays the pattern before and after a process change so you can use it to evaluate the team's performance after a significant process change. + +## Lead Time for Change + + DORA team definition: The time it takes for a commit to reach production. + + In Choreo, this translates into the time between committing and promoting a deployment to production. Although this approach may overlook any commits you push to production between two commits, it effectively assesses the efficiency of the review, approval, and CI/CD processes. Therefore, focusing on the production commits is adequate. If a team commits locally for extended periods without deploying to production, this gets reflected in the `Deployment Frequency` charts. + +### Snapshot view + +![Lead Time For Change Frequency Snapshot](../../assets/img/monitoring-and-insights/engineering-insights/lead-time-for-a-change-summary.png){.cInlineImage-small} + +The snapshot view of this metric displays the 95th percentile of the lead time for the selected time period. 95th percentile serves as a better representation as it filters out large outliers that can taint the average value. Lower lead times for change suggest that your organization has efficient processes for change review, approval, and CI/CD, while longer times suggest that the process needs to improve. Organizations can also use the categorization label to determine their standpoint on global standards. + +Additionally, Choreo also displays the percentage increase or decrease compared to the last time period. + +### Time series view + +![Lead Time For Change Frequency Time Series View](../../assets/img/monitoring-and-insights/engineering-insights/lead-time-for-a-change-chart.png){.cInlineImage-half} + +The time series view of this metric visualizes the lead time as a bar chart for the selected time period. The time is summed based on the ‘view by’ selector. To handle outliers, the y-axis employs a log scale that represents values read dynamically. Hovering over each bar displays the actual counts for the aggregated period. +Using this chart, organizations can identify trends in their release process. For example, organizations can identify the time of the year when lead time rises, such as summer break. Also, organizations can use this to benchmark and evaluate new process changes. For example, if you introduced a process to include peer programming and reviewing, this chart can be used to evaluate its effect on the lead time and provide leadership with factual information to proceed further. + +## Change failure rate + +The DORA team definition: The percentage of deployments causing a failure in production. + +In Choreo, this translates to the ratio of deployments causing production failures to the total number of deployments. If there is at least one incident reported against a deployment, Choreo considers that deployment as a failed deployment in production. Any deployment-time failures are not counted as production failures because such failures don't impact the end user. For this metric to be accurate, the organization is expected to open incidents adhering to the proper format as it is crucial for Choreo to identify production failures. + +### Snapshot view + +![Change Failure Rate Snapshot](../../assets/img/monitoring-and-insights/engineering-insights/change-failure-rate-summary.png){.cInlineImage-small} + +The snapshot view of this metric visualizes the change failure rate as a percentage for the selected time period. This will be the absolute percentage for the entire time period. When deciding on the time, the time of deployment is considered instead of the incident reported time. For example, the change failure rate for January 2023 will reflect the following: + - All deployments that happened within January. + - Any incidents that were reported at any time (in or after January) against the January deployments. + +This view helps leadership assess the quality of deliverables and identify areas for improvement. Higher rates suggest that the organization needs to improve its processes to bring in more quality assurance aspects such as improved code coverage and end-to-end test coverage. + +Additionally, Choreo also shows the percentage increase or decrease compared to the previous time period. + +### Time series view + +![Change Failure Rate Time Series](../../assets/img/monitoring-and-insights/engineering-insights/change-failure-rate-chart.png){.cInlineImage-half} + +The time series view of this metric displays it as a line chart with data points corresponding to the granularity selected by the ‘view by’ selector. The absolute percentage is shown for each granularity. Hovering over the line chart displays the actual counts for the aggregated period. +This chart helps leadership identify timely trends in product quality aspects. For example, this view displays the months of the year where the failure rate is high (for example, close to quarterly release/announcement dates). Also, you can use this to measure the effectiveness of changes introduced to improve quality. For example, if the organization introduced an end-to-end test pipeline integration to the PR approval process, they can use this view to factually observe the timely impact of that change and determine how it decreases the failure rate. + +## Mean Time to Recover(MTTR) + +The DORA team definition: The time it takes for an organization to recover from a production failure. + +In Choreo, this measures the time from identifying a production incident to resolving it. This metric reflects the responsiveness and agility of incident management teams. + +Choreo depends on the open and close times of incidents to gather the relevant information. Therefore, for the dashboards to be accurate, organizations must follow process guidelines to update and close incident tickets efficiently in their incident management system. + +### Snapshot view + +![Mean Time to Recovery Snapshot](../../assets/img/monitoring-and-insights/engineering-insights/mean-time-to-recovery-summary.png){.cInlineImage-small} + +The snapshot view for this metric displays the mean recovery time for the selected time period. Choreo dynamically adjusts the time unit to measure this metric for better readability. +This chart helps organizations evaluate the response time and agility of their incident handling teams, which in turn is an indication of stability. Higher MTTR means the leadership should look at new ways of improving the efficiency and agility of the teams handling incidents. + +### Time series view + +![Mean Time to Recovery Time Series](../../assets/img/monitoring-and-insights/engineering-insights/mean-time-to-recovery-chart.png){.cInlineImage-half} + +The time series view of this metric shows how the mean time to recovery changes over time on a granularity based on the ‘view by’ selector. Each time the `granularity mean` would be used as the aggregation factor. Hovering over the line chart displays the actual counts for the aggregated period. +This view helps leadership understand timely trends on mean time to recovery, such as higher values during holiday periods when there is less staff. Also, you can use this measurement to evaluate the effectiveness of process changes such as introducing an incident response plan. The trend view clearly shows the before and after statistics and the effectiveness of the process change. diff --git a/en/pe-docs/docs/insights/work-with-choreo-insights-api/access-the-choreo-insights-api.md b/en/pe-docs/docs/insights/work-with-choreo-insights-api/access-the-choreo-insights-api.md new file mode 100644 index 000000000..a99692fa8 --- /dev/null +++ b/en/pe-docs/docs/insights/work-with-choreo-insights-api/access-the-choreo-insights-api.md @@ -0,0 +1,72 @@ +# Access the Choreo Insights API + +The **Insights** page in the Choreo Console displays data retrieved from the Insights API exposed over the Internet. However, in some scenarios, you may need to retrieve data from external systems and implement custom dashboards to display the data. + +Choreo provides a secure and user-friendly approach to accomplish this requirement. Follow the steps given below: + +## Become a member of the Choreo System organization + +1. Access the Developer Portal of the `Choreo System` organization via [https://devportal.choreo.dev/choreosystem/applications](https://devportal.choreo.dev/choreosystem/applications) and sign in using your preferred method. + +2. To obtain access to the `Choreo System` organization, click **Request Access**. + + ![Request access](../../assets/img/monitoring-and-insights/work-with-choreo-insights-api/request-access.png){.cInlineImage-full} + +## Create an application and generate keys + +To create an application and generate keys, follow the steps below: + +1. To create a new application in the `Choreo System` organization, click **+ Create Application**. + +2. Enter a name for the application and click **Create**. This creates the application and takes you to the **Overview** page. + +3. To subscribe to the **Insights** API via the newly created application, follow the steps below: + 1. In the left navigation menu, click **Subscriptions**. + 2. In the **Subscription Management** pane, click **+ Add APIs**. + 3. Search for `Insights` and click **Add**. + +4. To generate credentials for the application, follow the steps given below: + 1. In the left navigation menu, click **Production** under **Credentials**. + 2. Click **Generate Credentials**. Choreo generates tokens and populates the **Consumer Key** and **Consumer Secret** fields in the **Application Keys** pane. + +5. To specify an appropriate token expiry time for the application, follow the steps given below: + 1. In the **Application Keys** pane, click to expand **Advanced Configurations**. + 2. Specify an appropriate value in the **Application access token expiry time** field and click **Update**. + + ![Update token expiry time](../../assets/img/monitoring-and-insights/work-with-choreo-insights-api/update-token-expirary-time.png){.cInlineImage-threeQuarter} + +6. Execute the following cURL command to generate an access token: + + ```bash + curl --location --request POST 'https://sts.choreo.dev/oauth2/token' \ + --header 'Authorization: Basic ' \ + --header 'Content-Type: application/x-www-form-urlencoded' \ + --data-urlencode 'grant_type=client_credentials' \ + --data-urlencode 'orgHandle=' \ + --data-urlencode 'scope=apim:api_manage' + ``` + + !!! info + To obtain your organization handle, follow the steps given below: + + 1. Sign in to [Choreo](https://console.choreo.dev/). + 2. In the top navigation menu, click the **Organization** list and select your organization. + 3. From the left navigation menu, click on **User Management**, then click **Users**. + 4. Click **Copy Handle**. + + You can use the generated token to access the Insights API exposed via [https://choreocontrolplane.choreo.dev/93tu/insights/1.0.0/query-api](https://choreocontrolplane.choreo.dev/93tu/insights/1.0.0/query-api). + + The following is a sample cURL command to invoke the Insights API: + + ```bash + curl --location --request POST 'https://choreocontrolplane.choreo.dev/93tu/insights/1.0.0/query-api' \ + --header 'Content-Type: application/json' \ + --header 'Authorization: Bearer ' \ + --data-raw '{"query":"query ($org: OrgFilter!) {listEnvironments(org: $org){id\n name}}","variables":{"org":{"orgId":""}}}' + ``` + + !!! tip + - When the token expires, you can generate a new token programmatically by making an API call to the token endpoint using the client credentials grant type. + - If a token theft occurs, you can revoke the token by making an API call to the revoke endpoint. + + ![Endpoints](../../assets/img/monitoring-and-insights/work-with-choreo-insights-api/endpoints.png){.cInlineImage-threeQuarter} diff --git a/en/pe-docs/docs/insights/work-with-choreo-insights-api/choreo-insights-api.md b/en/pe-docs/docs/insights/work-with-choreo-insights-api/choreo-insights-api.md new file mode 100644 index 000000000..d3b7721da --- /dev/null +++ b/en/pe-docs/docs/insights/work-with-choreo-insights-api/choreo-insights-api.md @@ -0,0 +1,4849 @@ +# Choreo Insights API + +The Choreo Insights API is a GraphQL API that allows you to retrieve data from external systems based on specific criteria. This guide describes the operations and schema-defined types you can use to retrieve data via the Choreo Insights API. + + - **Allowed operations:** [Queries](#query) + - **Schema-defined types:** [Objects](#objects), [Inputs](#inputs), [Enums](#enums), and [Scalars](#scalars) + +##Try out + +You can try out the Choreo Insights API with your data via [GraphQL Explorer](graphiql-explorer/index.html). + +!!! warning + The GraphQL Explorer is currently not compatible with the Safari web browser due to a [known issue](https://developer.apple.com/forums/thread/658688). + +## Query +The query root of the Choreo Insights GraphQL API. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldArgumentTypeDescription
listAllAPI[API] + +Fetches all the APIs with the given combination of tenant ID, environment ID, and organization ID. Optionally, you +can configure the provider parameter to further filter the APIs by a specific provider. + +
providerString + +The name of the API provider. + +
dataFilterDataFilter! + +The data filter. + +
listApplications[Application] + +Fetches all the applications with the given combination of tenant ID, environment ID, and organization ID. Optionally, you +can configure the applicationFilter parameter to further filter the applications by a specific application filter. + +
applicationFilterApplicationFilter + +The application filter. + +
dataFilterDataFilter! + +The data filter. + +
listProviders[Provider] + +Fetches all the API providers with the given combination of tenant ID, environment ID, and organization ID. + +
dataFilterDataFilter! + +The data filter. + +
listSubscribers[Subscriber] + +Fetches all the API subscribers with the given combination of tenant ID, environment ID, and organization ID. Optionally, you +can configure the subscriberFilter parameter to further filter the subscribers. + +
subscriberFilterSubscriberFilter + +The subscriber filter. + +
dataFilterDataFilter! + +The data filter. + +
listOrganizations[Organization] + +Fetches all the organizations of a user. + +
listEnvironments[Environment] + +Fetches all the environments of an organization. + +
orgOrgFilter! + +The organization filter. + +
projectIdString + +The project ID by which the results need to be filtered. It is optional to specify a value for this +parameter. Note that providing a project ID with an on-prem key is not allowed. + +
listTenants[String] + +Fetches all the tenants with the given combination of environment ID and organization ID. + +
tenantDataFilterTenantDataFilter! + +The tenant filter. + +
getTotalTrafficInt + +Returns the total traffic during the given time range for the specified combination of tenant ID, environment ID, +and organization ID. + +
filterTimeFilter! + +The time filter. + +
dataFilterDataFilter! + +The data filter. + +
getTotalErrorsInt + +Returns the total number of errors that occurred during the given time range for the specified combination of tenant +ID, environment ID, and organization ID. + +
filterTimeFilter! + +The time filter. + +
dataFilterDataFilter! + +The data filter. + +
getOverallLatencyFloat + +Returns the overall response latency (95th percentile value) during the given time range for the specified +combination of tenant ID, environment ID, and organization ID. + +
filterTimeFilter! + +The time filter. + +
dataFilterDataFilter! + +The data filter. + +
getLatencySummaryLatencySummary + +Returns the response latency value (95th percentile value) for each time granularity within the specified time range +for the given combination of tenant ID, environment ID, and organization ID. Optionally, you can configure the +latencySummaryFilter parameter to further filter the results. + +
filterTimeFilter! + +The time filter. + +
latencySummaryFilterLatencySummaryFilter + +The latency summary filter. + +
dataFilterDataFilter! + +The data filter. + +
getSuccessSummarySuccessSummary + +Returns the number of successful (2xx response code) hit count for each time granularity within the specified time +range for the given combination of tenant ID, environment ID, and organization ID. Optionally, you can configure the +granularity parameter to override the default granularity value. + +
filterTimeFilter! + +The time filter. + +
dataFilterDataFilter! + +The data filter. + +
granularityString + +The granularity value. + +
getErrorSummaryErrorSummary + +Returns the number of unsuccessful hits (i.e., the total of both 4xx and 5xx response codes) for each time +granularity within the specified time range for the given combination of tenant ID, environment ID, and organization +ID. Optionally, you can configure the granularity parameter to override the default granularity value. + +
filterTimeFilter! + +The time filter. + +
dataFilterDataFilter! + +The data filter. + +
granularityString + +The granularity value. + +
getErrorsByCategoryErrorsByCategory + +Returns the number of proxy errors (i.e., the total of both 4xx and 5xx response codes) by each error category +for each time granularity within the specified time range for the given combination of tenant ID, environment ID, +and organization ID. Optionally, you can configure the errorsByCategoryFilter parameter to further filter the +results. + +
timeFilterTimeFilter! + +The time filter. + +
errorsByCategoryFilterErrorsByCategoryFilter + +The errors by category filter. + +
dataFilterDataFilter! + +The data filter. + +
getErrorsDetailsDetailsOfErrors + +Returns details of each proxy error (for both 4xx and 5xx response codes) within the specified time range for +the given combination of tenant ID, environment ID, and organization ID. Optionally, you can configure the +errorsDetailsFilter parameter to further filter the results. + +
timeFilterTimeFilter! + +The time filter. + +
errorsDetailsFilterErrorsDetailsFilter + +The error details filter. + +
dataFilterDataFilter! + +The data filter. + +
getProxyTargetErrorsOverTime[ErrorsByStatusCodeCategory] + +Returns a list of hit counts for proxy and target errors for each time granularity within the specified time range +for the given combination of tenant ID, environment ID, and organization ID. The errors in each proxy and target +result set are grouped as 4xx, 5xx, and total. Optionally, you can configure the errorsByStatusCodeFilter +parameter to further filter the results. + +
timeFilterTimeFilter! + +The time filter. + +
errorsByStatusCodeFilterErrorsByStatusCodeFilter + +The errors by status code filter. + +
dataFilterDataFilter! + +The data filter. + +
getErrorsByStatusCodeErrorsByStatusCode + +Returns the hit count for each error response code (401, 404, and 500 etc.,) for each API within the specified +time range for the given combination of tenant ID, environment ID, and organization ID. + +
timeFilterTimeFilter! + +The time filter. + +
errorCountByStatusCodeFilterErrorCountByStatusCodeFilter! + +The error count by status code filter. + +
dataFilterDataFilter! + +The data filter. + +
getTotalErrorsByAPITotalError + +Returns the total proxy error hit count for an API across for the given combination of tenant ID, environment ID, +and organization ID. Optionally, you can configure the filter parameter to further filter the results by a given +time range. + +
filterTimeFilter + +The time filter. + +
dataFilterDataFilter! + +The data filter. + +
apiIdID! + +The API ID. + +
getAPIUsageOverTime[APIUsageOverTime] + +Returns a list of details related to the usage of each API over time for each time granularity within the specified +time range for the given combination of tenant ID, environment ID, and organization ID. Optionally, you can +configure the apiUsageOvertimeFilter parameter to further filter the results. + +
timeFilterTimeFilter! + +The time filter. + +
apiUsageOvertimeFilterAPIUsageOverTimeFilter + +The API usage overtime filter. + +
dataFilterDataFilter! + +The data filter. + +
getAPIUsageByAppOverTimeAPIUsageByAppOverTime + +Returns API usage by each application over time for each time granularity within the specified time range for the +given combination of tenant ID, environment ID, and organization ID. Optionally, you can configure the +apiUsageOvertimeFilter parameter to further filter the results. + +
timeFilterTimeFilter! + +The time filter. + +
apiUsageOvertimeFilterAPIUsageOverTimeFilter + +The API usage overtime filter. + +
dataFilterDataFilter! + +The data filter. + +
getAPIUsageByBackendOverTimeAPIUsageByBackendOverTime + +Returns API usage by each backend over time for each time granularity within the specified time range for the given +combination of tenant ID, environment ID, and organization ID. Optionally, you can configure the +apiUsageByBackendOverTimeFilter parameter to further filter the results. + +
timeFilterTimeFilter! + +The time filter. + +
apiUsageByBackendOverTimeFilterAPIUsageByBackendOverTimeFilter + +The API usage by backend overtime filter. + +
dataFilterDataFilter! + +The data filter. + +
getResourceUsageResourceUsages + +Returns API usage by resource within the specified time range for the given combination of tenant ID, environment +ID, and organization ID. Optionally, you can configure the resourceUsageFilter parameter to further filter the +results. + +
timeFilterTimeFilter! + +The time filter. + +
resourceUsageFilterResourceUsageFilter + +The resource usage filter. + +
dataFilterDataFilter! + +The data filter. + +
getTotalTrafficByAPIInt + +Returns the total hit count for an API for the given combination of tenant ID, environment ID, and organization ID. +Optionally, you can configure the filter parameter to further filter the results by a given time range. + +
filterTimeFilter + +The time filter. + +
dataFilterDataFilter! + +The data filter. + +
apiIdID! + +The API ID. + +
topSlowestAPIs[SlowAPI] + +Returns a list of top slowest APIs based on the response latency (95th percentile value) within the specified time +range for the given combination of tenant ID, environment ID, and organization ID. + +
filterTimeFilter! + +The time filter. + +
dataFilterDataFilter! + +The data filter. + +
limitInt! + +The limit for the slow APIs list. + +
getLatencyAPILatency + +Returns different latency category values (95th percentile values) for a given API over time for each time +granularity within the specified time range for the given combination of tenant ID, environment ID, and organization +ID. + +
timeFilterTimeFilter! + +The time filter. + +
latencyFilterLatencyFilter! + +The latency filter. + +
dataFilterDataFilter! + +The data filter. + +
getOverallLatencyByAPIOverallLatency + +Returns the overall response latency (95th percentile value) for an API for the given combination of tenant ID, +environment ID, and organization ID. Optionally, you can configure the filter parameter to further filter the +results by a given time range. + +
filterTimeFilter + +The time filter. + +
dataFilterDataFilter! + +The data filter. + +
apiIdID! + +The API ID. + +
getCacheHitsAndMissesCacheHits + +Return the total number of response cache hits, misses, and hit percentage for an API over time for each time +granularity within the specified time range for the given combination of tenant ID, environment ID, and +organization ID. + +
timeFilterTimeFilter! + +The time filter. + +
cacheFilterCacheFilter + +The cache filter. + +
dataFilterDataFilter! + +The data filter. + +
getTopPlatforms[Platform] + +Returns a list of top platforms ranked based on the hit count within the specified time range for the given +combination of tenant ID, environment ID, and organization ID. The result list includes the top nine platforms with +the respective hit count, and all the rest of the platforms are labeled as **Other** with the cumulated hit count. +Optionally, you can configure the deviceFilter parameter to further filter the results. + +
timeFilterTimeFilter! + +The time filter. + +
deviceFilterDeviceFilter + +The device filter. + +
dataFilterDataFilter! + +The data filter. + +
getTopUserAgents[UserAgent] + +Returns a list of top user agents ranked based on the hit count within the specified time range for the given +combination of tenant ID, environment ID, and organization ID. The result list includes the top nine user agents +with the respective hit count, and all the rest of the platforms are labeled as **Other** with the cumulated hit +count. Optionally, you can configure the deviceFilter parameter to further filter the results. + +
timeFilterTimeFilter! + +The time filter. + +
deviceFilterDeviceFilter + +The device filter. + +
dataFilterDataFilter! + +The data filter. + +
getAPIUsageByGeoLocation[UsageByGeoLocation] + +NOTE: Currently, this operation returns data only for on-premise environments. + +Returns API usage by country within the specified time range for the given combination of tenant ID, environment ID, +and organization ID. Optionally, you can configure the geoLocationFilter parameter to further filter the results. + +
timeFilterTimeFilter! + +The time filter. + +
geoLocationFilterGeoLocationFilter + +The geolocation filter. + +
dataFilterDataFilter! + +The data filter. + +
getAPIsUsageByApplications[APIUsageByApplication] + +Returns details relating to the usage of each API by application within the specified time range for the given +combination of tenant ID, environment ID, and organization ID. Optionally, you can configure the +apiUsageByAppFilter parameter to further filter the results. + +
timeFilterTimeFilter! + +The time filter. + +
apiUsageByAppFilterAPIUsageByAppFilter + +The API usage by app filter. + +
dataFilterDataFilter! + +The data filter. + +
getTopAPIsByAlertCountTopAPIsByAlertCount + +Returns top APIs ranked based on the alert count within the specified time range for the given combination of tenant +ID, environment ID, and organization ID. Optionally, you can configure the topAPIsByAlertCountFilter parameter to +further filter the results. + +
timeFilterTimeFilter! + +The time filter. + +
topAPIsByAlertCountFilterTopAPIsByAlertCountFilter + +The top APIs by alert count filter. + +
dataFilterDataFilter! + +The data filter. + +
getAlertSummaryAlertSummaries + +Returns a summary for each alert within the specified time range for the given combination of tenant ID, +environment ID, and organization ID. Optionally, you can configure the alertSummaryFilter parameter to further +filter the results. + +
timeFilterTimeFilter! + +The time filter. + +
alertSummaryFilterAlertSummaryFilter + +The alert summary filter. + +
dataFilterDataFilter! + +The data filter. + +
getSuccessAPIsUsageByApplications[SuccessAPIUsageByApplication] + +NOTE: This operation can only be invoked via using an on-prem key as the authentication header. + +Returns a list of successful hit counts (i.e., 2xx response codes) within the specified time range for each API, +grouped by each application. Optionally, you can configure the successAPIUsageByAppFilter parameter to further +filter the results. + +
timeFilterTimeFilter! + +The time filter. + +
successAPIUsageByAppFilterSuccessAPIUsageByAppFilter + +The successful API usage by application filter. + +
getSuccessAPIsUsageByApplicationsWithOnPremKey[SuccessAPIUsageByApplication] + +Returns a list of successful hit counts (i.e., 2xx response codes) within the specified time range for each API, +grouped by each application. Optionally, you can configure the successAPIUsageByAppFilter parameter to further +filter the results. + +
onPremKeyString! + +The value of the On-Prem key. + +
timeFilterTimeFilter! + +The time filter. + +
successAPIUsageByAppFilterSuccessAPIUsageByAppFilter + +The successful API usage by application filter. + +
getCustomReportOvertimeCustomReportOvertime + +Returns the summary of hits or latency data as specified for the selected time duration, grouped by time spans. + +
dataFilterDataFilter! + +The data filter. + +
timeFilterTimeFilter! + +The time filter. + +
metricMetric! + +The metric for which data needs to be retrieved. + +
groupByFields[GroupByField]! + +The column/field by which data needs to be retrieved. + +
groupByValues[String]! + +The value used to filter by the groupByField. + +
granularityString! + +The granularity value for which data is retrieved. + +
getCustomReportTopOvertimeCustomReportTopOvertime + +Returns the summary of hits or latency data as specified for the selected time duration, grouped by time spans for +the top N values for the selected groupByField. + +
dataFilterDataFilter! + +The data filter. + +
timeFilterTimeFilter! + +The time filter. + +
metricMetric! + +The metric for which data needs to be retrieved. + +
groupByFields[GroupByField]! + +The column/field by which the data should be grouped. + +
groupByValues[String]! + +The value used to filter by the groupByField. + +
granularityString! + +The granularity value for which data is retrieved. + +
getGroupByValues[[String]] + +Returns a list of value sets by which you can group the data available for the selected groupBy fields. + +
dataFilterDataFilter! + +The data filter. + +
groupByFields[GroupByField]! + +The column/field for which the API needs to retrieve distinct values. + +
groupByValues[String]! + +The value used to filter by the groupByField. + +
+ +## Objects + +### API + +Represents API details. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldArgumentTypeDescription
idID! + +The ID of the API. + +
nameString! + +The API name. + +
versionString! + +The API version. + +
providerString! + +The API provider name. + +
+ +### APILatency + +Represents latency values for a single API over time. + + + + + + + + + + + + + + + + + + + + + + +
FieldArgumentTypeDescription
summary[Latency] + +A list containing latency category values over time. Returns an empty array if no data is available. + +
granularityString! + +The granularity value for which data is retrieved. + +
+ +### APIUsage + +Represents the API usage for a single timestamp. The timestamp is calculated based on the granularity value provided. + + + + + + + + + + + + + + + + + + + + + + +
FieldArgumentTypeDescription
timeSpanString! + +Represents a timestamp value that is calculated based on the specified granularity value. For example, if the +granularity value is 1d, the timestamp represents the start of the day calculated adhering to the timezone +provided in the time filter. +e.g., timeSpan: '2021-06-21T00:00:00.0000000+05:30' + +
countInt! + +The API usage count. + +
+ +### APIUsageByApp + +Represents API usage across APIs by a single application. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldArgumentTypeDescription
applicationIdID! + +The application ID. + +
applicationNameString! + +The application name. + +
applicationOwnerString! + +The name of the application owner. + +
usage[APIUsage] + +A list containing the APIs usage values. Returns an empty array if no data is available. + +
+ +### APIUsageByAppOverTime + +Represents API usage across APIs by applications over time. + + + + + + + + + + + + + + + + + + + + + + +
FieldArgumentTypeDescription
usage[APIUsageByApp] + +A list containing the API usage values across APIs, grouped by the application. Returns an empty array if no data is +available. + +
granularityString! + +The granularity value for which data is retrieved. + +
+ +### APIUsageByApplication + +Represents a single API usage by a single application. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldArgumentTypeDescription
apiIdString! + +The ID of the API. + +
applicationIdString! + +The Application ID. + +
applicationNameString! + +The application name. + +
applicationOwnerString! + +The name of the application owner. + +
countInt! + +The usage of the API by the application. + +
+ +### APIUsageByBackend + +Represents API usage across APIs by a single backend. + + + + + + + + + + + + + + + + + + + + + + +
FieldArgumentTypeDescription
backendString! + +The name of the backend. + +
usage[APIUsage] + +A list containing the APIs usage values. Returns an empty array if no data is available. + +
+ +### APIUsageByBackendOverTime + +Represents API usage across APIs by each backend over time. + + + + + + + + + + + + + + + + + + + + + + +
FieldArgumentTypeDescription
usage[APIUsageByBackend] + +A list containing the API usage values across APIs by each backend. Returns an empty array if no data is available. + +
granularityString! + +The granularity value for which data is retrieved. + +
+ +### APIUsageOverTime + +Represents a single API usage over time. + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldArgumentTypeDescription
apiIdID + +The ID of the API. + +
usage[APIUsage] + +A list containing the API usage values. Returns an empty array if no data is available. + +
granularityString! + +The granularity value for which data is retrieved. + +
+ +### AlertSummaries + +Represents alert summaries. + + + + + + + + + + + + + + + + + + + + + + +
FieldArgumentTypeDescription
usage[AlertSummary] + +A list containing the alert summary for each alert. Returns an empty array if no data is available. + +
paginationPagination! + +The pagination details. + +
+ +### AlertSummary + +Represents a summary for an alert. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldArgumentTypeDescription
apiIdID! + +The ID of the API. + +
timestampString! + +Represents a timestamp value that is calculated based on the specified granularity value. For example, if the +granularity value is 1d, the timestamp represents the start of the day calculated adhering to the timezone +provided in the time filter. +e.g., timeSpan: '2021-06-21T00:00:00.0000000+05:30' + +
categoryString! + +The alert category. Possible values are LATENCY and TRAFFIC. + +
metricString! + +The alert metric. Possible values are RESPONSE_LATENCY and TOTAL_TRAFFIC. + +
severityString! + +The severity level of the alert. Possible values are LOW, MEDIUM, and HIGH. + +
messageString! + +The alert details. + +
+ +### Application + +Represents application details. + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldArgumentTypeDescription
idID! + +The Application ID. + +
nameString! + +The application name. + +
ownerString! + +The name of the application owner. + +
+ +### CacheHit + +Represents the response cache hits and misses for a single timestamp. The timestamp is calculated based on the +granularity value provided. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldArgumentTypeDescription
timeSpanString! + +Represents a timestamp value that is calculated based on the specified granularity value. For example, if the +granularity value is 1d, the timestamp represents the start of the day calculated adhering to the timezone +provided in the time filter. +e.g., timeSpan: '2021-06-21T00:00:00.0000000+05:30' + +
hitsInt! + +The number of times the response cache was hit. + +
missesInt! + +The number of times the response cache was missed. + +
hitPercentageFloat! + +The response cache hits as a percentage of the sum of hits and misses. + +
+ +### CacheHits + +Represents the response cache hits and misses over time. + + + + + + + + + + + + + + + + + + + + + + +
FieldArgumentTypeDescription
summary[CacheHit] + +A list containing cache hits, misses, and the hit percentage over time. Returns an empty array if no data is +available. + +
granularityString! + +The granularity value for which data is retrieved. + +
+ +### CustomReportGroupBy + +Represents the usage data overtime for the selected parameters of a specific groupByValue. + + + + + + + + + + + + + + + + + + + + + + +
FieldArgumentTypeDescription
groupByValueID! + +The distinct group-by value that is used as an ID. + +
usage[CustomReportUsage] + +A list containing the usage values. This returns an empty array if no data is available. + +
+ +### CustomReportOvertime + +Represents usage data overtime for the selected parameters. + + + + + + + + + + + + + + + + + + + + + + +
FieldArgumentTypeDescription
usage[CustomReportUsage] + +A list containing the usage values. This returns an empty array if no data is available. + +
granularityString! + +The granularity value for which data is retrieved. + +
+ +### CustomReportTopOvertime + +Represents usage data overtime for the selected parameters grouped by the top N groupByValues. + + + + + + + + + + + + + + + + + + + + + + +
FieldArgumentTypeDescription
usage[CustomReportGroupBy] + +A list containing the usage values grouped by the selected groupByField. This returns an empty array if no data is +available. + +
granularityString! + +The granularity value for which data is retrieved. + +
+ +### CustomReportUsage + +Represents usage data for a single timestamp in CustomReports. + + + + + + + + + + + + + + + + + + + + + + +
FieldArgumentTypeDescription
timeSpanString! + +Represents a timestamp value that is calculated based on the specified granularity value. For example, if the +granularity value is 1d, the timestamp represents the start of the day calculated adhering to the timezone +provided in the time filter. +e.g., timeSpan: '2021-06-21T00:00:00.0000000+05:30' + +
valueInt! + +The usage value (Hit Count/ Latency). + +
+ +### DetailsOfErrors + +Represents error details over time. + + + + + + + + + + + + + + + + + + + + + + +
FieldArgumentTypeDescription
usage[ErrorDetails]! + +A list containing error details over time. Returns an empty array if no data is available. + +
paginationPagination! + +The pagination details. + +
+ +### Environment + +Represents an environment. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldArgumentTypeDescription
idString! + +The environment ID. + +
externalEnvIdString! + +The external environment ID. + +
internalEnvIdString + +The internal environment ID. + +
sandboxEnvIdString + +The sandbox environment ID. + +
nameString! + +The environment name. + +
typeEnvironmentType! + +The environment type. A Choreo environment is labeled as CHOREO, a private Choreo environment is labeled as +CHOREO_PRIVATE, and the on-premise environment is labeled as ON_PREM. + +
+ +### ErrorCountByCategory + +Represents the number of errors from each category for a single timestamp. The timestamp is calculated according to the +provided granularity value. If you select some categories, the error counts are retrieved only for those categories, +and a null value is shown for the other categories that are not selected. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldArgumentTypeDescription
timeSpanString! + +Represents a timestamp value that is calculated based on the specified granularity value. For example, if the +granularity value is 1d, the timestamp represents the start of the day calculated adhering to the timezone +provided in the time filter. +e.g., timeSpan: '2021-06-21T00:00:00.0000000+05:30' + +
authInt + +The count of authorization errors. + +
targetConnectivityInt + +The count of target connectivity errors. + +
throttledInt + +The count of throttling errors. + +
otherInt + +The count of other errors. + +
+ +### ErrorCountByCode + +Represents the error count for a single error status code. + + + + + + + + + + + + + + + + + + + + + + +
FieldArgumentTypeDescription
statusCodeString! + +The error status code. + +
countInt! + +The error count. + +
+ +### ErrorCountByCodeForAPI + +Represents the error count for each status code for a single API. + + + + + + + + + + + + + + + + + + + + + + +
FieldArgumentTypeDescription
apiIdID! + +The ID of the API. + +
errorCountByCode[ErrorCountByCode] + +A list containing the error count for each error status code. Returns an empty array if no data is available. + +
+ +### ErrorDetails + +Represents details of an error for a single timestamp. The timestamp is calculated according to the granularity value +provided. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldArgumentTypeDescription
apiIdID + +The ID of the API. + +
timeSpanString! + +Represents a timestamp value that is calculated based on the specified granularity value. For example, if the +granularity value is 1d, the timestamp represents the start of the day calculated adhering to the timezone +provided in the time filter. +e.g., timeSpan: '2021-06-21T00:00:00.0000000+05:30' + +
applicationIdString + +The Application ID. + +
applicationNameString + +The application name. + +
applicationOwnerString + +The name of the application owner. + +
reasonString! + +The reason for the error. + +
countInt! + +The error count. + +
+ +### ErrorStatusCodeCategoryCounts + +Represents errors by the main status code (4xx or 5xx) and the total error count. + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldArgumentTypeDescription
_4xxInt + +The number of client errors. + +
_5xxInt + +The number of server errors. + +
totalInt + +The total number of client and server errors. + +
+ +### ErrorSummary + +Provides the unsuccessful usage (i.e., 4xx and 5xx response codes) summary across all APIs. + + + + + + + + + + + + + + + + + + + + + + +
FieldArgumentTypeDescription
summary[ErrorValue]! + +A list containing unsuccessful usage values. Returns an empty array if no data is available. + +
granularityString! + +The granularity value for which data is retrieved. + +
+ +### ErrorValue + +Represents the unsuccessful request count (i.e., 4xx and 5xx response codes) for a single timestamp. The timestamp +is calculated based on the granularity value provided. + + + + + + + + + + + + + + + + + + + + + + +
FieldArgumentTypeDescription
timeSpanString + +Represents a timestamp value that is calculated based on the specified granularity value. For example, if the +granularity value is 1d, the timestamp represents the start of the day calculated adhering to the timezone +provided in the time filter. +e.g., timeSpan: '2021-06-21T00:00:00.0000000+05:30' + +
errorCountInt + +Represents the error request count. + +
+ +### ErrorsByCategory + +Represents the errors by category over time. + + + + + + + + + + + + + + + + + + + + + + +
FieldArgumentTypeDescription
errors[ErrorCountByCategory] + +A list containing the error count for each error category over time. Returns an empty array if no data is available. + +
granularityString! + +The granularity value for which data is retrieved. + +
+ +### ErrorsByStatusCode + +Represents the error counts grouped by status code for each API. + + + + + + + + + + + + + + + + + + + + + + +
FieldArgumentTypeDescription
errors[ErrorCountByCodeForAPI]! + +A list containing the error count for each status code for each API. Returns an empty array if no data is available. + +
paginationPagination! + +Pagination details. + +
+ +### ErrorsByStatusCodeCategory + +Represents the error category values (grouped as 4xx, 5xx, and total) for both proxy and target errors for a +single timestamp. The timestamp is calculated based on the granularity value provided. + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldArgumentTypeDescription
timeSpanString! + +Represents a timestamp value that is calculated based on the specified granularity value. For example, if the +granularity value is 1d, the timestamp represents the start of the day calculated adhering to the timezone +provided in the time filter. +e.g., timeSpan: '2021-06-21T00:00:00.0000000+05:30' + +
proxyErrorStatusCodeCategoryCounts + +Represents proxy-related errors categorized as client errors (4xx response codes) or server errors (5xx response +codes), and the total of both categories. + +
targetErrorStatusCodeCategoryCounts + +Represents target-related errors categorized as client errors (4xx response codes) or server errors (5xx +response codes), and the total of both categories. + +
+ +### Latency + +Represents latency values for each latency category for a single timestamp. The timestamp is calculated based on the +granularity value provided. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldArgumentTypeDescription
timeSpanString + +Represents a timestamp value that is calculated based on the specified granularity value. For example, if the +granularity value is 1d, the timestamp represents the start of the day calculated adhering to the timezone +provided in the time filter. +e.g., timeSpan: '2021-06-21T00:00:00.0000000+05:30' + +
responseInt + +The response latency (95th percentile) in milliseconds (ms). + +
backendInt + +The backend latency (95th percentile) in milliseconds (ms). + +
requestMediationInt + +The request mediation latency (95th percentile) in milliseconds (ms). + +
responseMediationInt + +The response mediation latency (95th percentile) in milliseconds (ms). + +
responseMedianInt + +The median (50th percentile) of the response latency in milliseconds (ms). + +
backendMedianInt + +The median (50th percentile) of the backend latency in milliseconds (ms). + +
requestMediationMedianInt + +The median (50th percentile) of the request mediation latency in milliseconds (ms). + +
responseMediationMedianInt + +The median (50th percentile) of the response mediation latency in milliseconds (ms). + +
+ +### LatencySummary + +Provides the latency summary. + + + + + + + + + + + + + + + + + + + + + + +
FieldArgumentTypeDescription
summary[LatencyValue]! + +A list containing latency values. Returns an empty array if no data is available. + +
granularityString! + +The granularity value for which data is retrieved. + +
+ +### LatencyValue + +Represents the latency value for a single timestamp. The timestamp is calculated according to the provided granularity +value. + + + + + + + + + + + + + + + + + + + + + + +
FieldArgumentTypeDescription
timeSpanString! + +Represents a timestamp value that is calculated based on the specified granularity value. For example, if the +granularity value is 1d, the timestamp represents the start of the day calculated adhering to the timezone +provided in the time filter. +e.g., timeSpan: '2021-06-21T00:00:00.0000000+05:30' + +
latencyTimeFloat! + +Represents the latency (95th percentile) time in milliseconds (ms). + +
+ +### Organization + +Represents an organization. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldArgumentTypeDescription
idString! + +The organization ID. + +
uuidID! + +The organization UUID. + +
handleString! + +The organization handle name. + +
nameString! + +The organization name. + +
+ +### OverallLatency + +Represents the overall latency values. + + + + + + + + + + + + + + + + + +
FieldArgumentTypeDescription
responseFloat + +The response latency (95th percentile value) in milliseconds (ms). + +
+ +### Pagination + +Represents pagination details. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldArgumentTypeDescription
totalInt! + +The total number of results. + +
limitInt! + +The number of items in the result set. + +
offsetInt! + +The offset value for the result set. + +
sortByString! + +The sorting column name of the result set. + +
sortOrderString! + +The sorting order of the result set. Possible values are asc and desc. + +
+ +### Platform + +Represents a platform. + + + + + + + + + + + + + + + + + + + + + + +
FieldArgumentTypeDescription
platformString! + +The name of the platform. + +
countInt! + +The usage of the platform. + +
+ +### Provider + +Represents API Provider details. + + + + + + + + + + + + + + + + + +
FieldArgumentTypeDescription
nameString! + +The API provider name. + +
+ +### ResourceUsage + +Represents the usage of a single API resource. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldArgumentTypeDescription
apiIdID! + +The ID of the API. + +
apiResourceTemplateString! + +The API resource template. + +
apiMethodString! + +The API method. + +
countInt! + +The usage of the API resource. + +
+ +### ResourceUsages + +Represents API resource usages. + + + + + + + + + + + + + + + + + + + + + + +
FieldArgumentTypeDescription
usage[ResourceUsage] + +A list with the usage of each API resource. Returns an empty array if no data is available. + +
paginationPagination! + +Pagination details. + +
+ +### SlowAPI + +A slow API identified based on the response latency (95th percentile). + + + + + + + + + + + + + + + + + + + + + + +
FieldArgumentTypeDescription
apiIdID! + +The ID of the API. + +
latencyInt! + +Represents the latency (95th percentile) time in milliseconds (ms). + +
+ +### Subscriber + +Represents API Subscriber details. + + + + + + + + + + + + + + + + + +
FieldArgumentTypeDescription
nameString! + +The name of the API subscriber. + +
+ +### SuccessAPIUsageByApplication + +Represents successful usages(that have resulted in the 2xx response code) of an API by an application. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldArgumentTypeDescription
apiIdString! + +The ID of the API. + +
apiNameString! + +The name of the API. + +
apiVersionString! + +The version of the API. + +
apiCreatorTenantDomainString! + +The tenant domain of the API creator. + +
applicationIdString! + +The application ID. + +
applicationNameString! + +The name of the application. + +
applicationOwnerString! + +The name of the application owner. + +
countInt!
+ +### SuccessSummary + +Provides the successful (2xx response code) usage summary across all the APIs. + + + + + + + + + + + + + + + + + + + + + + +
FieldArgumentTypeDescription
summary[SuccessValue]! + +A list containing successful usage values. Returns an empty array if no data is available. + +
granularityString! + +The granularity value for which data is retrieved. + +
+ +### SuccessValue + +Represents the successful request count (i.e., requests that have received the 2xx response code) for a single +timestamp. The timestamp is calculated according to the granularity value provided. + + + + + + + + + + + + + + + + + + + + + + +
FieldArgumentTypeDescription
timeSpanString! + +Represents a timestamp value that is calculated based on the specified granularity value. For example, if the +granularity value is 1d, the timestamp represents the start of the day calculated adhering to the timezone +provided in the time filter. +e.g., timeSpan: '2021-06-21T00:00:00.0000000+05:30' + +
requestCountInt! + +Represents the successful request count. + +
+ +### TopAPIByAlertCount + +Represents a top API by alert count. + + + + + + + + + + + + + + + + + + + + + + +
FieldArgumentTypeDescription
apiIdID! + +The ID of the API. + +
countInt! + +The alert count. + +
+ +### TopAPIsByAlertCount + +Represents the top APIs by alert count. + + + + + + + + + + + + + + + + + + + + + + +
FieldArgumentTypeDescription
usage[TopAPIByAlertCount] + +A list containing top APIs by alert count. Returns an empty array if no data is available. + +
paginationPagination! + +The pagination details. + +
+ +### TotalError + +Represents the total errors. + + + + + + + + + + + + + + + + + +
FieldArgumentTypeDescription
proxyInt + +The proxy-related error count. + +
+ +### UsageByGeoLocation + +Represents the usage of a single API in a single country. + + + + + + + + + + + + + + + + + + + + + + +
FieldArgumentTypeDescription
countryString! + +The name of the country. + +
countInt! + +The usage of the API. + +
+ +### UserAgent + +Represents a user agent. + + + + + + + + + + + + + + + + + + + + + + +
FieldArgumentTypeDescription
userAgentString! + +The name of the user agent. + +
countInt! + +The usage of the user agent. + +
+ +## Inputs + +### APIUsageByAppFilter + +Filters the API usage by application results. + + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldTypeDescription
apiIds[String] + +The results are filtered for the list of APIs you specify here. A maximum of five API IDs can be defined. + +
appIds[String] + +The results are filtered for the list of applications you specify here. A maximum of five application IDs can be +defined. + +
subscribers[String] + +The results are filtered for the list of subscribers you specify here. A maximum of five subscriber IDs can be +defined. + +
+ +### APIUsageByBackendOverTimeFilter + +Filters the results for API usage by backend over time. + + + + + + + + + + + + + + + + + + + + + +
FieldTypeDescription
apiIds[String] + +The results are filtered for the list of APIs you specify here. A maximum of five API IDs can be defined. + +
granularityString + +The granularity value that is used for data retrieval. If the granularity value is not set, the default granularity +for the related time range is applied. The possible granularity values that you can specify are 1m, 15m, 1h, +1d, and 7d. + +
+ +### APIUsageOverTimeFilter + +Filters the results for API usage over time. + + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldTypeDescription
apiIds[String] + +The results are filtered for the list of APIs you specify here. A maximum of five API IDs can be defined. + +
appIds[String] + +The results are filtered for the list of applications you specify here. A maximum of five application IDs can be +defined. + +
granularityString + +The granularity value that is used for data retrieval. If the granularity value is not set, the default granularity +for the related time range is applied. The possible granularity values that you can specify are 1m, 15m, 1h, +1d, and 7d. + +
+ +### AlertSummaryFilter + +Filters the alerts summary results. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldTypeDescription
paginationFilterPaginationFilter + +The pagination filter. + +
searchFilterSearchFilter + +The search filter. + +
apiIds[String] + +The results are filtered for the list of APIs you specify here. A maximum of five API IDs can be defined. + +
categoryString + +The alert category by which the results need to be filtered. The available categories to select are TRAFFIC and +LATENCY. + +
+ +### ApplicationFilter + +Filters applications by the application owner and API IDs. + + + + + + + + + + + + + + + + + + + + + +
FieldTypeDescription
ownerString
apiIds[String] + +The results are filtered for the list of APIs you specify here. A maximum of five API IDs can be defined. + +
+ +### CacheFilter + +Filters response cache results. + + + + + + + + + + + + + + + + + + + + + +
FieldTypeDescription
apiIdString + +The results are filtered by the API ID specified here. + +
granularityString + +The granularity value that is used for data retrieval. If the granularity value is not set, the default granularity +for the related time range is applied. The possible granularity values that you can specify are 1m, 15m, 1h, +1d, and 7d. + +
+ +### DataFilter + +Filters results by the given combination of organization, environment, and tenant. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldTypeDescription
orgIdString! + +The organization by which the results need to be filtered. It is required to specify a value for this parameter. + +
environmentIdString + +The environment ID by which the results need to be filtered. It is required to specify a value for this parameter. + +
environmentIds[String] + +The environment IDs by which the results need to be filtered. It is required to specify a value for this parameter. + +
tenantString! + +The name of the tenant by which the results need to be filtered. It is required to specify a value for this +parameter. + +
projectIdString + +The project ID by which the results need to be filtered. It is optional to specify a value for this +parameter. Note that providing a project ID with an on-prem key is not allowed. + +
+ +### DeviceFilter + +Filters results related to devices. + + + + + + + + + + + + + + + + +
FieldTypeDescription
apiIds[String] + +The results are filtered for the list of APIs you specify here. A maximum of five API IDs can be defined. + +
+ +### ErrorCountByStatusCodeFilter + +Filters errors by status code results. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldTypeDescription
apiIdString + +The results are filtered by the API ID specified here. + +
errorTypeErrorType! + +The type of the error. It is required to specify a value for this parameter. + +
errorCodeTypeErrorCodeType + +The error code type. If this parameter is not configured, both client-related error response codes (401, 404, +etc.) and server-related response codes (500, 501, etc.) are included in the result set. + +
paginationFilterPaginationFilter + +The pagination filter. + +
+ +### ErrorsByCategoryFilter + +Filters errors by category results. + + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldTypeDescription
apiIdString + +The ID of the API. + +
categories[String] + +The list of categories by which the results need to be filtered. Category values that you can specify here are +AUTH, TARGET_CONNECTIVITY, THROTTLED, and OTHER. + +
granularityString + +The granularity value that is used for data retrieval. If the granularity value is not set, the default granularity +for the related time range is applied. The possible granularity values that you can specify are 1m, 15m, 1h, +1d, and 7d. + +
+ +### ErrorsByStatusCodeFilter + +Filters errors by status code results. + + + + + + + + + + + + + + + + + + + + + +
FieldTypeDescription
apiIdString + +The results are filtered by the API ID specified here. + +
granularityString + +The granularity value that is used for data retrieval. If the granularity value is not set, the default granularity +for the related time range is applied. The possible granularity values that you can specify are 1m, 15m, 1h, +1d, and 7d. + +
+ +### ErrorsDetailsFilter + +Filters the results for error details. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldTypeDescription
apiIdString + +The results are filtered by the API ID specified here. + +
appIdString + +The application ID by which the results need to be filtered. + +
categoryString + +The error category by which the results need to be filtered. The error category that you can specify here must be +one of the AUTH TARGET_CONNECTIVITY, THROTTLED, and OTHER values. + +
granularityString + +The granularity value that is used for data retrieval. If the granularity value is not set, the default granularity +for the related time range is applied. The possible granularity values that you can specify are 1m, 15m, 1h, +1d, and 7d. + +
paginationFilterPaginationFilter + +The pagination filter. + +
searchFilterSearchFilter + +The search filter. + +
+ +### GeoLocationFilter + +Filters the API usage by geolocation results. + + + + + + + + + + + + + + + + +
FieldTypeDescription
apiIds[String] + +The results are filtered for the list of APIs you specify here. + +
+ +### LatencyFilter + +Filters latency results. + + + + + + + + + + + + + + + + + + + + + +
FieldTypeDescription
apiIdString! + +The results are filtered by the API ID specified here. It is required to specify a value for this parameter. + +
granularityString + +The granularity value that is used for data retrieval. If the granularity value is not set, the default granularity +for the related time range is applied. The possible granularity values that you can specify are 1m, 15m, 1h, +1d, and 7d. + +
+ +### LatencySummaryFilter + +Filters latency summary results. + + + + + + + + + + + + + + + + + + + + + +
FieldTypeDescription
apiIdString + +The results are filtered by the API ID specified here. + +
granularityString + +The granularity value that is used for data retrieval. If the granularity value is not set, the default granularity +for the related time range is applied. The possible granularity values that you can specify are 1m, 15m, 1h, +1d, and 7d. + +
+ +### OrgFilter + +Filters results for the given organization. + + + + + + + + + + + + + + + + +
FieldTypeDescription
orgIdString! + +The ID of the organization by which the results need to be filtered. It is required to specify a value for this +parameter. + +
+ +### PaginationFilter + +Filters related to pagination. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldTypeDescription
limitInt + +The total number of rows in the result set. This value must be a positive integer. If this limit value is not set, +the total number of rows is five by default. + +
offsetInt + +The offset value to set when filtering results. This value must be zero or a positive integer. If you do not specify +an offset value, the default offset value (i.e., 0) applies. + +
sortByString + +The column name by which the results are sorted. If the sortBy value is not set, the default column of the related +operation that is available for sorting purposes is used. + +
sortOrderString + +The order in which the results are sorted. Possible values are asc (to sort in ascending order) and desc (to +sort in descending order). If no value is specified, the results are sorted in ascending order by default (except +for count-specific operations such as getTopAPIsByAlertCount where the results are always sorted in descending +order). + +
+ +### ResourceUsageFilter + +Filters resource usage results. + + + + + + + + + + + + + + + + + + + + + +
FieldTypeDescription
paginationFilterPaginationFilter + +The pagination filter. + +
searchFilterSearchFilter + +The search filter. + +
+ +### SearchFilter + +Filters results by searching matching results for the provided search text. + + + + + + + + + + + + + + + + + + + + + +
FieldTypeDescription
apiIds[String] + +The list of API IDs that need to be searched with the given search text. Note that it is not possible to define API +IDs without a search text in the search filter. + +
searchTextString! + +Text which needs to be searched among the results. It is required to specify a value for this parameter. + +
+ +### SubscriberFilter + +Filters the subscriber results. + + + + + + + + + + + + + + + + +
FieldTypeDescription
apiIds[String] + +The results are filtered for the list of APIs you specify here. A maximum of five API IDs can be defined. + +
+ +### SuccessAPIUsageByAppFilter + +Filters successful API usage by application results. + + + + + + + + + + + + + + + + + + + + + +
FieldTypeDescription
apiIds[String] + +The list of API IDs by which the results need to be filtered. + +
tenantDomains[String] + +The tenant domain name by which the results need to be filtered. + +
+ +### TenantDataFilter + +Filters results by the tenant. + + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldTypeDescription
orgIdString! + +The ID of the organization by which the results need to be filtered. It is required to specify a value for this +parameter. + +
envIdString + +The ID of the environment by which the results need to be filtered. It is required to specify a value for this +parameter. + +
environmentIds[String] + +The environment IDs by which the results need to be filtered. It is required to specify a value for this parameter. + +
+ +### TimeFilter + +Filters results by the provided date range. + + + + + + + + + + + + + + + + + + + + + +
FieldTypeDescription
fromString! + +The start date of the time range. The date specified here must be a date earlier than the date specified via the +to parameter. If the defined date and time entry do not have a timezone, the UTC time zone (z) is used. It is +required to specify a value for this parameter. +e.g., '2021-08-16T12:00:00.000+05:30'. + +
toString! + +The end date of the time range. The date specified here must be a date later than the date specified via the from +parameter. If the defined date and time entry do not have a timezone, the UTC time zone (z) is used. It is +required to specify a value for this parameter. +e.g., '2021-08-16T12:30:00.000+05:30'. + +
+ +### TopAPIsByAlertCountFilter + +Filters the top APIs by alert count results. + + + + + + + + + + + + + + + + + + + + + +
FieldTypeDescription
paginationFilterPaginationFilter + +The pagination filter. + +
searchFilterSearchFilter + +The search filter. + +
+ +## Enums + +### EnvironmentType + +Represents an error type. + + + + + + + + + + + + + + + + + + + + +
ValueDescription
CHOREO + +The Choreo environments. + +
CHOREO_PRIVATE + +The private data-plane Choreo environments. + +
ON_PREM + +The On-Premise environments. + +
+ +### ErrorCodeType + +Represents an error code type. + + + + + + + + + + + + + + + + +
ValueDescription
_4XX + +The client-side errors. + +
_5XX + +The server-side errors. + +
+ +### ErrorType + +Represents an error type. + + + + + + + + + + + + + + + + +
ValueDescription
PROXY + +The proxy-related errors. + +
TARGET + +The target-related errors. + +
+ +### GroupByField + +Represents an groupByField used in CustomReports. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ValueDescription
API_NAME + +The API name. + +
API_VERSION + +The API version. + +
API_RESOURCE_TEMPLATE + +The API resource template. + +
API_METHOD + +The API method. + +
API_CREATOR + +The API creator. + +
APPLICATION_NAME + +The name of the application. + +
APPLICATION_OWNER + +The owner of the application. + +
DESTINATION + +The destination. + +
USER_AGENT + +The user Agent. + +
PLATFORM + +The platform. + +
TARGET_RESPONSE_CODE + +The target response code. + +
+ +### Metric + +Represents a metric used in CustomReports. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ValueDescription
HIT_COUNT + +The number of API calls. + +
RESPONSE_CACHE_HIT + +The number of API calls that used the response cache. + +
REQUEST_MEDIATION_LATENCY + +The request mediation latency. + +
RESPONSE_MEDIATION_LATENCY + +The response mediation latency. + +
BACKEND_LATENCY + +The backend latency. + +
TOTAL_LATENCY + +The total latency. + +
API_ERRORS + +The number of hits for which API errors are returned. + +
TARGET_ERRORS + +The number of hits for which target errors are returned. + +
+ +## Scalars + +### Boolean + +The Boolean scalar type represents true or false. + +### Float + +The Float scalar type represents signed double-precision fractional values as specified by [IEEE 754](https://en.wikipedia.org/wiki/IEEE_floating_point). + +### ID + +The ID scalar type represents a unique identifier, often used to re-fetch an object or as the key for a cache. The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When expected as an input type, any string (such as "4") or integer (such as 4) input value is accepted as an ID. + +### Int + +The Int scalar type represents non-fractional signed whole numeric values. Int can represent values between -(2^31) and 2^31 - 1. + +### String + +The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text. + diff --git a/en/site/monitoring-and-insights/work-with-choreo-insights-api/graphiql-explorer/asset-manifest.json b/en/pe-docs/docs/insights/work-with-choreo-insights-api/graphiql-explorer/asset-manifest.json similarity index 100% rename from en/site/monitoring-and-insights/work-with-choreo-insights-api/graphiql-explorer/asset-manifest.json rename to en/pe-docs/docs/insights/work-with-choreo-insights-api/graphiql-explorer/asset-manifest.json diff --git a/en/site/monitoring-and-insights/work-with-choreo-insights-api/graphiql-explorer/favicon.ico b/en/pe-docs/docs/insights/work-with-choreo-insights-api/graphiql-explorer/favicon.ico similarity index 100% rename from en/site/monitoring-and-insights/work-with-choreo-insights-api/graphiql-explorer/favicon.ico rename to en/pe-docs/docs/insights/work-with-choreo-insights-api/graphiql-explorer/favicon.ico diff --git a/en/site/monitoring-and-insights/work-with-choreo-insights-api/graphiql-explorer/index.html b/en/pe-docs/docs/insights/work-with-choreo-insights-api/graphiql-explorer/index.html similarity index 100% rename from en/site/monitoring-and-insights/work-with-choreo-insights-api/graphiql-explorer/index.html rename to en/pe-docs/docs/insights/work-with-choreo-insights-api/graphiql-explorer/index.html diff --git a/en/site/monitoring-and-insights/work-with-choreo-insights-api/graphiql-explorer/insight.config.js b/en/pe-docs/docs/insights/work-with-choreo-insights-api/graphiql-explorer/insight.config.js similarity index 92% rename from en/site/monitoring-and-insights/work-with-choreo-insights-api/graphiql-explorer/insight.config.js rename to en/pe-docs/docs/insights/work-with-choreo-insights-api/graphiql-explorer/insight.config.js index 5ece3345f..c0d9cc240 100644 --- a/en/site/monitoring-and-insights/work-with-choreo-insights-api/graphiql-explorer/insight.config.js +++ b/en/pe-docs/docs/insights/work-with-choreo-insights-api/graphiql-explorer/insight.config.js @@ -16,7 +16,7 @@ window.__RUNTIME_CONFIG__ = { grant_type: 'urn:ietf:params:oauth:grant-type:token-exchange', subject_token_type: 'urn:ietf:params:oauth:token-type:jwt', requested_token_type: 'urn:ietf:params:oauth:token-type:jwt', - scope: 'apim:admin' + scope: 'apim:admin apim:api_view apim:api_manage apim:api_import_export apim:api_list_view' } }, INSIGHTS_API_URL: 'https://choreocontrolplane.choreo.dev/93tu/insights/1.0.0/query-api', diff --git a/en/site/monitoring-and-insights/work-with-choreo-insights-api/graphiql-explorer/manifest.json b/en/pe-docs/docs/insights/work-with-choreo-insights-api/graphiql-explorer/manifest.json similarity index 100% rename from en/site/monitoring-and-insights/work-with-choreo-insights-api/graphiql-explorer/manifest.json rename to en/pe-docs/docs/insights/work-with-choreo-insights-api/graphiql-explorer/manifest.json diff --git a/en/site/monitoring-and-insights/work-with-choreo-insights-api/graphiql-explorer/static/css/2.dff3c244.chunk.css b/en/pe-docs/docs/insights/work-with-choreo-insights-api/graphiql-explorer/static/css/2.dff3c244.chunk.css similarity index 100% rename from en/site/monitoring-and-insights/work-with-choreo-insights-api/graphiql-explorer/static/css/2.dff3c244.chunk.css rename to en/pe-docs/docs/insights/work-with-choreo-insights-api/graphiql-explorer/static/css/2.dff3c244.chunk.css diff --git a/en/site/monitoring-and-insights/work-with-choreo-insights-api/graphiql-explorer/static/css/2.dff3c244.chunk.css.map b/en/pe-docs/docs/insights/work-with-choreo-insights-api/graphiql-explorer/static/css/2.dff3c244.chunk.css.map similarity index 100% rename from en/site/monitoring-and-insights/work-with-choreo-insights-api/graphiql-explorer/static/css/2.dff3c244.chunk.css.map rename to en/pe-docs/docs/insights/work-with-choreo-insights-api/graphiql-explorer/static/css/2.dff3c244.chunk.css.map diff --git a/en/site/monitoring-and-insights/work-with-choreo-insights-api/graphiql-explorer/static/css/main.dd389ba7.chunk.css b/en/pe-docs/docs/insights/work-with-choreo-insights-api/graphiql-explorer/static/css/main.dd389ba7.chunk.css similarity index 100% rename from en/site/monitoring-and-insights/work-with-choreo-insights-api/graphiql-explorer/static/css/main.dd389ba7.chunk.css rename to en/pe-docs/docs/insights/work-with-choreo-insights-api/graphiql-explorer/static/css/main.dd389ba7.chunk.css diff --git a/en/site/monitoring-and-insights/work-with-choreo-insights-api/graphiql-explorer/static/css/main.dd389ba7.chunk.css.map b/en/pe-docs/docs/insights/work-with-choreo-insights-api/graphiql-explorer/static/css/main.dd389ba7.chunk.css.map similarity index 100% rename from en/site/monitoring-and-insights/work-with-choreo-insights-api/graphiql-explorer/static/css/main.dd389ba7.chunk.css.map rename to en/pe-docs/docs/insights/work-with-choreo-insights-api/graphiql-explorer/static/css/main.dd389ba7.chunk.css.map diff --git a/en/site/monitoring-and-insights/work-with-choreo-insights-api/graphiql-explorer/static/js/2.e5757962.chunk.js b/en/pe-docs/docs/insights/work-with-choreo-insights-api/graphiql-explorer/static/js/2.e5757962.chunk.js similarity index 100% rename from en/site/monitoring-and-insights/work-with-choreo-insights-api/graphiql-explorer/static/js/2.e5757962.chunk.js rename to en/pe-docs/docs/insights/work-with-choreo-insights-api/graphiql-explorer/static/js/2.e5757962.chunk.js diff --git a/en/site/monitoring-and-insights/work-with-choreo-insights-api/graphiql-explorer/static/js/2.e5757962.chunk.js.LICENSE.txt b/en/pe-docs/docs/insights/work-with-choreo-insights-api/graphiql-explorer/static/js/2.e5757962.chunk.js.LICENSE.txt similarity index 100% rename from en/site/monitoring-and-insights/work-with-choreo-insights-api/graphiql-explorer/static/js/2.e5757962.chunk.js.LICENSE.txt rename to en/pe-docs/docs/insights/work-with-choreo-insights-api/graphiql-explorer/static/js/2.e5757962.chunk.js.LICENSE.txt diff --git a/en/site/monitoring-and-insights/work-with-choreo-insights-api/graphiql-explorer/static/js/2.e5757962.chunk.js.map b/en/pe-docs/docs/insights/work-with-choreo-insights-api/graphiql-explorer/static/js/2.e5757962.chunk.js.map similarity index 100% rename from en/site/monitoring-and-insights/work-with-choreo-insights-api/graphiql-explorer/static/js/2.e5757962.chunk.js.map rename to en/pe-docs/docs/insights/work-with-choreo-insights-api/graphiql-explorer/static/js/2.e5757962.chunk.js.map diff --git a/en/site/monitoring-and-insights/work-with-choreo-insights-api/graphiql-explorer/static/js/main.78fb288a.chunk.js b/en/pe-docs/docs/insights/work-with-choreo-insights-api/graphiql-explorer/static/js/main.78fb288a.chunk.js similarity index 100% rename from en/site/monitoring-and-insights/work-with-choreo-insights-api/graphiql-explorer/static/js/main.78fb288a.chunk.js rename to en/pe-docs/docs/insights/work-with-choreo-insights-api/graphiql-explorer/static/js/main.78fb288a.chunk.js diff --git a/en/site/monitoring-and-insights/work-with-choreo-insights-api/graphiql-explorer/static/js/main.78fb288a.chunk.js.map b/en/pe-docs/docs/insights/work-with-choreo-insights-api/graphiql-explorer/static/js/main.78fb288a.chunk.js.map similarity index 100% rename from en/site/monitoring-and-insights/work-with-choreo-insights-api/graphiql-explorer/static/js/main.78fb288a.chunk.js.map rename to en/pe-docs/docs/insights/work-with-choreo-insights-api/graphiql-explorer/static/js/main.78fb288a.chunk.js.map diff --git a/en/site/monitoring-and-insights/work-with-choreo-insights-api/graphiql-explorer/static/js/runtime-main.8245b2d9.js b/en/pe-docs/docs/insights/work-with-choreo-insights-api/graphiql-explorer/static/js/runtime-main.8245b2d9.js similarity index 100% rename from en/site/monitoring-and-insights/work-with-choreo-insights-api/graphiql-explorer/static/js/runtime-main.8245b2d9.js rename to en/pe-docs/docs/insights/work-with-choreo-insights-api/graphiql-explorer/static/js/runtime-main.8245b2d9.js diff --git a/en/site/monitoring-and-insights/work-with-choreo-insights-api/graphiql-explorer/static/js/runtime-main.8245b2d9.js.map b/en/pe-docs/docs/insights/work-with-choreo-insights-api/graphiql-explorer/static/js/runtime-main.8245b2d9.js.map similarity index 100% rename from en/site/monitoring-and-insights/work-with-choreo-insights-api/graphiql-explorer/static/js/runtime-main.8245b2d9.js.map rename to en/pe-docs/docs/insights/work-with-choreo-insights-api/graphiql-explorer/static/js/runtime-main.8245b2d9.js.map diff --git a/en/site/monitoring-and-insights/work-with-choreo-insights-api/graphiql-explorer/static/media/gilmer-bold.1b0f0f29.eot b/en/pe-docs/docs/insights/work-with-choreo-insights-api/graphiql-explorer/static/media/gilmer-bold.1b0f0f29.eot similarity index 100% rename from en/site/monitoring-and-insights/work-with-choreo-insights-api/graphiql-explorer/static/media/gilmer-bold.1b0f0f29.eot rename to en/pe-docs/docs/insights/work-with-choreo-insights-api/graphiql-explorer/static/media/gilmer-bold.1b0f0f29.eot diff --git a/en/site/monitoring-and-insights/work-with-choreo-insights-api/graphiql-explorer/static/media/gilmer-bold.703ca0a7.woff2 b/en/pe-docs/docs/insights/work-with-choreo-insights-api/graphiql-explorer/static/media/gilmer-bold.703ca0a7.woff2 similarity index 100% rename from en/site/monitoring-and-insights/work-with-choreo-insights-api/graphiql-explorer/static/media/gilmer-bold.703ca0a7.woff2 rename to en/pe-docs/docs/insights/work-with-choreo-insights-api/graphiql-explorer/static/media/gilmer-bold.703ca0a7.woff2 diff --git a/en/site/monitoring-and-insights/work-with-choreo-insights-api/graphiql-explorer/static/media/gilmer-bold.9cf9669b.ttf b/en/pe-docs/docs/insights/work-with-choreo-insights-api/graphiql-explorer/static/media/gilmer-bold.9cf9669b.ttf similarity index 100% rename from en/site/monitoring-and-insights/work-with-choreo-insights-api/graphiql-explorer/static/media/gilmer-bold.9cf9669b.ttf rename to en/pe-docs/docs/insights/work-with-choreo-insights-api/graphiql-explorer/static/media/gilmer-bold.9cf9669b.ttf diff --git a/en/site/monitoring-and-insights/work-with-choreo-insights-api/graphiql-explorer/static/media/gilmer-bold.fb7355ad.woff b/en/pe-docs/docs/insights/work-with-choreo-insights-api/graphiql-explorer/static/media/gilmer-bold.fb7355ad.woff similarity index 100% rename from en/site/monitoring-and-insights/work-with-choreo-insights-api/graphiql-explorer/static/media/gilmer-bold.fb7355ad.woff rename to en/pe-docs/docs/insights/work-with-choreo-insights-api/graphiql-explorer/static/media/gilmer-bold.fb7355ad.woff diff --git a/en/site/monitoring-and-insights/work-with-choreo-insights-api/graphiql-explorer/static/media/gilmer-medium.18a9997c.woff2 b/en/pe-docs/docs/insights/work-with-choreo-insights-api/graphiql-explorer/static/media/gilmer-medium.18a9997c.woff2 similarity index 100% rename from en/site/monitoring-and-insights/work-with-choreo-insights-api/graphiql-explorer/static/media/gilmer-medium.18a9997c.woff2 rename to en/pe-docs/docs/insights/work-with-choreo-insights-api/graphiql-explorer/static/media/gilmer-medium.18a9997c.woff2 diff --git a/en/site/monitoring-and-insights/work-with-choreo-insights-api/graphiql-explorer/static/media/gilmer-medium.721edb3d.ttf b/en/pe-docs/docs/insights/work-with-choreo-insights-api/graphiql-explorer/static/media/gilmer-medium.721edb3d.ttf similarity index 100% rename from en/site/monitoring-and-insights/work-with-choreo-insights-api/graphiql-explorer/static/media/gilmer-medium.721edb3d.ttf rename to en/pe-docs/docs/insights/work-with-choreo-insights-api/graphiql-explorer/static/media/gilmer-medium.721edb3d.ttf diff --git a/en/site/monitoring-and-insights/work-with-choreo-insights-api/graphiql-explorer/static/media/gilmer-medium.8feb26bf.eot b/en/pe-docs/docs/insights/work-with-choreo-insights-api/graphiql-explorer/static/media/gilmer-medium.8feb26bf.eot similarity index 100% rename from en/site/monitoring-and-insights/work-with-choreo-insights-api/graphiql-explorer/static/media/gilmer-medium.8feb26bf.eot rename to en/pe-docs/docs/insights/work-with-choreo-insights-api/graphiql-explorer/static/media/gilmer-medium.8feb26bf.eot diff --git a/en/site/monitoring-and-insights/work-with-choreo-insights-api/graphiql-explorer/static/media/gilmer-medium.9eb8c454.woff b/en/pe-docs/docs/insights/work-with-choreo-insights-api/graphiql-explorer/static/media/gilmer-medium.9eb8c454.woff similarity index 100% rename from en/site/monitoring-and-insights/work-with-choreo-insights-api/graphiql-explorer/static/media/gilmer-medium.9eb8c454.woff rename to en/pe-docs/docs/insights/work-with-choreo-insights-api/graphiql-explorer/static/media/gilmer-medium.9eb8c454.woff diff --git a/en/site/monitoring-and-insights/work-with-choreo-insights-api/graphiql-explorer/static/media/gilmer-regular.34195eed.woff b/en/pe-docs/docs/insights/work-with-choreo-insights-api/graphiql-explorer/static/media/gilmer-regular.34195eed.woff similarity index 100% rename from en/site/monitoring-and-insights/work-with-choreo-insights-api/graphiql-explorer/static/media/gilmer-regular.34195eed.woff rename to en/pe-docs/docs/insights/work-with-choreo-insights-api/graphiql-explorer/static/media/gilmer-regular.34195eed.woff diff --git a/en/site/monitoring-and-insights/work-with-choreo-insights-api/graphiql-explorer/static/media/gilmer-regular.4e0de531.ttf b/en/pe-docs/docs/insights/work-with-choreo-insights-api/graphiql-explorer/static/media/gilmer-regular.4e0de531.ttf similarity index 100% rename from en/site/monitoring-and-insights/work-with-choreo-insights-api/graphiql-explorer/static/media/gilmer-regular.4e0de531.ttf rename to en/pe-docs/docs/insights/work-with-choreo-insights-api/graphiql-explorer/static/media/gilmer-regular.4e0de531.ttf diff --git a/en/site/monitoring-and-insights/work-with-choreo-insights-api/graphiql-explorer/static/media/gilmer-regular.ac841c91.woff2 b/en/pe-docs/docs/insights/work-with-choreo-insights-api/graphiql-explorer/static/media/gilmer-regular.ac841c91.woff2 similarity index 100% rename from en/site/monitoring-and-insights/work-with-choreo-insights-api/graphiql-explorer/static/media/gilmer-regular.ac841c91.woff2 rename to en/pe-docs/docs/insights/work-with-choreo-insights-api/graphiql-explorer/static/media/gilmer-regular.ac841c91.woff2 diff --git a/en/site/monitoring-and-insights/work-with-choreo-insights-api/graphiql-explorer/static/media/gilmer-regular.dadefd19.eot b/en/pe-docs/docs/insights/work-with-choreo-insights-api/graphiql-explorer/static/media/gilmer-regular.dadefd19.eot similarity index 100% rename from en/site/monitoring-and-insights/work-with-choreo-insights-api/graphiql-explorer/static/media/gilmer-regular.dadefd19.eot rename to en/pe-docs/docs/insights/work-with-choreo-insights-api/graphiql-explorer/static/media/gilmer-regular.dadefd19.eot diff --git a/en/site/monitoring-and-insights/work-with-choreo-insights-api/graphiql-explorer/static/media/logout.ab831324.svg b/en/pe-docs/docs/insights/work-with-choreo-insights-api/graphiql-explorer/static/media/logout.ab831324.svg similarity index 100% rename from en/site/monitoring-and-insights/work-with-choreo-insights-api/graphiql-explorer/static/media/logout.ab831324.svg rename to en/pe-docs/docs/insights/work-with-choreo-insights-api/graphiql-explorer/static/media/logout.ab831324.svg diff --git a/en/pe-docs/docs/k8s-operations/containers/configure-container-resources-commands-and-arguments.md b/en/pe-docs/docs/k8s-operations/containers/configure-container-resources-commands-and-arguments.md new file mode 100644 index 000000000..6db1f8155 --- /dev/null +++ b/en/pe-docs/docs/k8s-operations/containers/configure-container-resources-commands-and-arguments.md @@ -0,0 +1,72 @@ +# Configure Container Resources, Commands, and Arguments + +In Choreo, you can view detailed information about the container that comprises a component, such as its image tag, the corresponding commit ID, any imposed resource usage limits, and so on. + +Each component in Choreo is limited to a single main container. + +![Container details](../../assets/img/devops-and-ci-cd/containers/containers-view.png){.cInlineImage-full} + +!!! info "Resource Limits" + Resource limits ensure that a single component does not take up more resources than it requires, which can affect other workloads on the data plane. If a process exceeds the allocated memory limit, the corresponding container will be forcefully shut down and restarted. If the process exceeds the allocated CPU limit, it gets throttled and can result in significant latencies in compute and I/O operations. + +Choreo allows you to edit the default container configuration depending on your requirement. + +## Update container configurations + +Follow these steps to update container configurations: + +1. Sign in to the [Choreo Console](https://console.choreo.dev/). +2. In the Choreo Console top navigation menu, select the **Organization**, then the **Project** and the relevant **Component**. +3. In the left navigation menu, click **K8s Operations** and then click **Containers**. +4. On the **Containers** page, click **Edit** to update the corresponding container configuration. +5. Apply the necessary changes and click **Save**. + + ![Edit container configurations](../../assets/img/devops-and-ci-cd/containers/edit-container-form.png){.cInlineImage-full} + +The following topics walk you through the container configuration changes you can apply. + +### Update resource requests and limits + +!!! info "Note" + The capability to update resource requests and limits is only available in paid pricing plans. + +To update resource requests and limits, move the corresponding slider to a required position. A resource request cannot be less than its corresponding limit. + + +### Set the image pull policy + +You can select one of the following options as the image pull policy. + +- **Always**: The image is always pulled from the container registry, even if a matching tag is already present in the data plane. +- **If Not Present** - The image is pulled from the container registry only if a matching image is not present in the data plane. + + !!! tip + + The recommended option is **If Not Present**. + + +### Specify container ports + +You can specify appropriate values for the **Container Port** and **Service Port**. The **Service Port** is the port exposed outside of the container to your project-scoped endpoint. If you do not know the value to specify as the **Service Port**, specify the **Container Port** value in both fields. + +!!! tip + + You do not need to configure port values manually for Ballerina components. The capability to edit port values is primarily for containerized/Dockerfile-based components. + + +You can also select an appropriate **Protocol**. + +### Define a command and arguments for the container + +You can define a command and arguments for a container when you want to provide or override the `ENTRYPOINT` of a container. For example, in a scenario where you want to run legacy or third-party applications, you would want to provide or override the `ENTRYPOINT` of a container. + +![Container command and arguments example](../../assets/img/devops-and-ci-cd/containers/example-container-cmd-and-args.png){.cInlineImage-half} + +When you define a command and arguments, + +- It specifies the `ENTRYPOINT` array and it is not executed within a shell. +- Variable references `$(VAR_NAME)` are expanded using the container's environment. If a variable cannot be resolved, the reference in the input string will be unchanged. +- `$$` are reduced to `$`, which allows escaping the `$(VAR_NAME)` syntax. This means that `"$$(VAR_NAME)"` produces the string literal `"$(VAR_NAME)"`. +- Escaped references are never expanded, regardless of whether the variable exists or not. + +The `ENTRYPOINT` of the container image is used if you do not define a command and arguments for the container. diff --git a/en/pe-docs/docs/k8s-operations/manage-configurations-and-secrets.md b/en/pe-docs/docs/k8s-operations/manage-configurations-and-secrets.md new file mode 100644 index 000000000..0c8dea695 --- /dev/null +++ b/en/pe-docs/docs/k8s-operations/manage-configurations-and-secrets.md @@ -0,0 +1,110 @@ +# Manage Configurations and Secrets + +Choreo allows you to easily manage and version your component's configurations and secrets as **file mounts** or **environment variables**. + +!!! info "Note" + All configurations and secrets applied to a Choreo component are stored in an encrypted secret vault in the cloud data plane, which is managed by WSO2. + If you are on a private data plane, the configurations and secrets are stored in an Azure key vault or AWS secret manager attached to your data plane in your cloud environment. + +## The difference between configurations and secrets + +Choreo considers all configurations and secrets to be sensitive content when storing them, but gives you the option to choose between secret or configuration when you create a file mount or an environment variable. + +- **Secrets** are write-only. Once you create a secret, you cannot see or retrieve its content via the Choreo Console. However, you can overwrite the existing content at any time. +- **Configurations** can be read and updated via the Choreo Console after you create them. + + !!!info "Note" + + If you want to include sensitive data such as database passwords, cloud credentials, service accounts, and so on, the recommended approach is to use a secret instead of a configuration. + +## Apply a file mount to your container + +Follow these steps to apply a file mount to a component you have created: + +1. Sign in to the [Choreo Console](https://console.choreo.dev/). +2. In the Choreo Console top navigation menu, select the **Organization**, then the **Project** and finally the relevant **Component**. +3. In the left navigation menu, click **K8s Operations** and then click **Configs & Secrets**. +4. Click **+ Create**. +5. In the **Create a Config or Secret** pane, click **File Mount**. +6. If you want to create the file mount as a secret, select **Mark as a Secret**. Otherwise, proceed to the next step. + + !!!info "Note" + + If you create the file mount as a secret, you will not be able to read the file content after you create the file mount. + +7. In the **Display Name** field, specify a name for the file mount. + + !!!tip + + The display name does not affect the file mount or its content. It is only a reference to identify the configuration or secret you create. + +8. In the **File Mount Path** field, specify where to mount the file inside the container. Use an absolute file path with the file name and extension if applicable. + + !!!tip + + The file name in the mount path does not need to match the configuration name or the name of the file you upload. + +9. Upload a configuration file or copy and paste the configuration content into the editor. + +10. Click **Create**. + + !!!info "Note" + + Configurations and secrets are applied immediately to your environment on creation. To ensure that the container reflects the new content, your existing running replicas undergo a rolling restart. + +## Apply environment variables to your container + +Follow these steps to apply environment variables to a component you have created: + +1. Sign in to the [Choreo Console](https://console.choreo.dev/). +2. In the Choreo Console top navigation menu, select the **Organization**, then the **Project** and finally the relevant **Component**. +3. In the left navigation menu, click **K8s Operations** and then click **Configs & Secrets**. +4. Click **+ Create**. +5. In the **Create a Config or Secret** pane, click **Environment Variables**. +6. If you want to create the environment variable values as secrets, select **Mark as a Secret**. Otherwise, proceed to the next step. + + !!!info "Note" + + If you create environment variables as secrets, you will not be able to read the values you set for the environment variables after you create them. + +7. In the **Display Name** field, specify a name to identify the configuration or secret. + + !!!tip + + The display name you specify does not affect the environment variables you set. It is only a reference to identify the configuration or secret you create. + +8. Under **Add Environment Variables**, specify the necessary environment variables as key-value pairs. You can click **Add Item** to add any number of environment variables. + +9. Click **Create**. + +## Update an existing configuration or secret + +Follow these steps to update a configuration or secret you have defined: + +1. Sign in to the [Choreo Console](https://console.choreo.dev/). +2. In the Choreo Console top navigation menu, select the **Organization**, then the **Project** and finally the relevant **Component**. +3. In the left navigation menu, click **K8s Operations** and then click **Configs & Secrets**. +4. Click the edit icon corresponding to the configuration or secret you want to update. +5. Apply the necessary changes and click **Save**. + +## Delete an existing configuration or secret + +Follow these steps to delete a configuration or secret you have defined: + +1. Sign in to the [Choreo Console](https://console.choreo.dev/). +2. In the Choreo Console top navigation menu, select the **Organization**, then the **Project** and finally the relevant **Component**. +3. In the left navigation menu, click **K8s Operations** and then click **Configs & Secrets**. +4. Click the delete icon corresponding to the configuration or secret you want to delete. +5. Enter the name of the configuration or secret to confirm deletion. +6. Click **Delete**. + +## Manage Ballerina configurables + +Choreo manages the [Ballerina configurables](https://ballerina.io/learn/by-example/configurable-variables/) for the Ballerina components you create. + +When you deploy or promote a Ballerina application, you can modify the Ballerina configurables via the **Deploy** page. + +!!!tip + + You can use configurables instead of environment variables to add file mounts to a Ballerina component. + Environment variables are primarily for components written in other languages. diff --git a/en/pe-docs/docs/k8s-operations/runtime/view-runtime-details.md b/en/pe-docs/docs/k8s-operations/runtime/view-runtime-details.md new file mode 100644 index 000000000..c7ae182b2 --- /dev/null +++ b/en/pe-docs/docs/k8s-operations/runtime/view-runtime-details.md @@ -0,0 +1,59 @@ +# View Runtime Details + +In Choreo, you can view details about running replicas of a component in a specific environment (i.e., Development or Production). + +To view the runtime details of a component, follow the steps given below: + +1. Sign in to the [Choreo Console](https://console.choreo.dev/). +2. In the Choreo Console top navigation menu, select the **Organization**, then the **Project** and the relevant **Component**. +3. In the left navigation menu, click **K8s Configurations** and then click **Runtime**. This opens the **Runtime** page populated with data retrieved from the underlying Choreo data plane. + +![Runtime details](../../assets/img/devops-and-ci-cd/runtime/runtime-view.png){.cInlineImage-full} + +The runtime details you can see here are analogous to a _zoomed-in_ view of a specific environment on the **Deploy** page. + +The following topics walk you through the specific details you can view and actions you can perform via the **Runtime** page. + +## Redeploy a release + +On the **Runtime** page, you can click **Redeploy Release** to immediately redeploy all resources, including configurations and secrets, to a specific environment. This triggers a rolling update to sync all the latest changes to the data plane. + +!!! info "What is a release?" + A release in Choreo uniquely identifies an underlying deployment of a component to an environment for a given version. For example, if you deploy a component to two environments across two versions, the component will have four active releases. + +The capability to redeploy a release also allows you to quickly restart all the running replicas of a component in a specific environment. + +## View running instances + +The running instances you see on the **Runtime** page provide insights into the active replicas of your component in the selected environment. + +- You can view details of each active replica and its associated real-time CPU and memory usage, status, restarts, and the time of the last activity. +- If you want to see the real-time logs and information on conditions and events of a replica, click the menu icon of the replica and then click **Real-time Logs** or **Conditions & Events** depending on what you need to view. These options provide insights that help to diagnose issues in deployments. + + ![Running instances](../../assets/img/devops-and-ci-cd/runtime/running-instaces.png){.cInlineImage-full} + + !!! info "Note" + - All metrics such as the total and replica-level CPU and memory usage displayed on the **Runtime** page are real-time data and are instantaneous representations of a component's current state. + - You can take a look at the observability metrics of a component to see historical data and usage trends. +### Observe real-time container logs + +Unlike the logs available in the **Observability Metrics** of a component, these logs are fetched in real-time from the data plane and are not historical. Therefore, you can only see logs of active containers and the last shutdown container. + +![Real-time container logs](../../assets/img/devops-and-ci-cd/runtime/realtime-container-logs.png){.cInlineImage-full} + +- **Display Previous Logs:** Enable to retrieve logs from the last shutdown/crashed/restarted container of an instance. +- **Since Seconds**: Specify the duration in seconds to fetch corresponding logs. +- **Filter Logs**: Enable to filter and displays matching log lines. This is a fuzzy string search. + +### View container conditions and events + +Conditions and events provide information necessary to troubleshoot failing deployments. + +![Container conditions and events](../../assets/img/devops-and-ci-cd/runtime/container-conditions-and-events.png){.cInlineImage-full} + +If a component is not behaving as expected and you cannot detect any issues via the application logs, these events can provide necessary debugging information, such as the following: + +- Failing health checks (liveness and readiness probes). +- Missing or invalid configuration/secret mounts. +- Missing or invalid storage volume mounts. +- Scheduling issues in the underlying data plane. diff --git a/en/pe-docs/docs/k8s-operations/scaling/autoscale-component-replicas.md b/en/pe-docs/docs/k8s-operations/scaling/autoscale-component-replicas.md new file mode 100644 index 000000000..41357dd2e --- /dev/null +++ b/en/pe-docs/docs/k8s-operations/scaling/autoscale-component-replicas.md @@ -0,0 +1,33 @@ +# Autoscale Component Replicas + +Choreo allows you to automatically scale your component replicas up or down in number based on resource consumption to ensure high availability. + +!!! info "Note" + Autoscaling capabilities are only available in paid plans for private data plane organizations. + In the free tier, components run in a single-replica, low-availability mode. + +![Scale component replicas](../../assets/img/devops-and-ci-cd/scaling/scaling-view.png){.cInlineImage-full} + +Follow these steps to configure autoscaling for a component: + +1. Sign in to the [Choreo Console](https://console.choreo.dev/). +2. In the Choreo Console top navigation menu, select the **Organization**, then the **Project** and finally the relevant **Component** for which you want to configure autoscaling. +3. In the left navigation menu, click **K8s Operations** and then click **Scaling**. +4. On the **Scaling** page, you can change the scaling parameters. + +The following parameters allow you to scale component replicas: + +- **Min replicas**: The minimum number of replicas to run at any given time. It is recommended to keep the value at a minimum of `2`. +- **Max replicas**: The maximum number of replicas to scale up to. In the cloud data plane, this is restricted to a maximum of `5`. There is no restriction on the value in private data planes. +- **CPU Threshold**: The average CPU utilization across all running replicas. If the CPU utilization across all active instances reaches the threshold, the number of active replicas automatically scales up until the average CPU utilization falls below the threshold. +- **Memory Threshold**: The average memory usage across all running replicas. Like the **CPU Threshold**, if all active instances reach the memory threshold, the number of active replicas automatically scales up until the average memory usage falls below the threshold. + +!!! tip + If you update a scaling parameter, it may not immediately reflect in the Choreo Console because the change can take some time to propagate. + +!!! info "Run a fixed number of replicas" + If you want to run exactly `3` replicas for a component, you must set the minimum and maximum replicas to `3`. + +!!! warning "Scale to zero" + - Although it is possible to set the minimum number of replicas to `0`, your component does not scale to zero automatically during low usage. It can only go down to `1` replica. + - Setting both the minimum and maximum replicas to `0` suspends the deployment. diff --git a/en/pe-docs/docs/k8s-operations/scaling/autoscale-components-with-scale-to-zero.md b/en/pe-docs/docs/k8s-operations/scaling/autoscale-components-with-scale-to-zero.md new file mode 100644 index 000000000..f59fb7040 --- /dev/null +++ b/en/pe-docs/docs/k8s-operations/scaling/autoscale-components-with-scale-to-zero.md @@ -0,0 +1,73 @@ +# Autoscale Components with Scale-to-Zero + +Choreo provides the scale-to-zero capability for HTTP applications you deploy in the data plane. This lets you run your components in a serverless mode. + +Scale to zero is very useful in lower environments, where you can significantly reduce infrastructure costs by scaling down idle workloads. In production environments, you can also use scale-to-zero capability if your application's behavior aligns with this feature behavior. In the paid tier, if you want to run your application with more guaranteed high availability, it is recommended to choose HPA (Horizontal Pod Autoscaler) scaling method and configure a minimum replica count of 2 or higher. + +## How Scale to Zero works in Choreo + +!!! info + For service components and web-apps you create after February 23, 2024, Choreo enables the scale-to-zero feature by default. + +When Scale to Zero is enabled, your apps will automatically scale down to zero unless they receive HTTP traffic. When the application receives an HTTP request, your workload quickly scales up from zero to handle the request. When a new request is received by the deployment, the deployment will scale up to one replica and serve the request. When the deployment remains idle for a set period (approximately 5 minutes), it will automatically scale back to zero until a new request is received. + +When Scale to Zero is enabled, you can set the maximum number of replicas for deployments with this capability. Choreo dynamically scales deployments up to meet high HTTP traffic demand, up to the specified number of replicas. If the pending requests surpass the defined threshold under **Number of pending requests to spawn a new pod**, Choreo automatically adds a new replica to handle the increased load. + +![Free User - Scale to Zero](../../assets/img/devops-and-ci-cd/scaling/scale-to-zero-view.png){.cInlineImage-full} + +## Enable scale to zero + +For service components and web-apps you create after February 23, 2024, Choreo enables the scale-to-zero feature by default. When deploying or promoting the component, the deployment will automatically scale-to-zero. +Upon the next request to the deployed service, a replica will be created to serve the request. + +!!! note + - For the services which contain at least one endpoint with the network visibility as **Project**, Choreo will not automatically scale-to-zero those components when you deploy or promote them. + - HTTP services that run on a port other than the below list of ports will not automatically scale-to-zero your component when deploying or promoting: 5000, 6000, 7000, 8000, 9000, 7070 to 7079, 8080 to 8089, and 9090 to 9099 or 8290. + + +To enable scale-to-zero for service components created before February 23, 2024, follow the steps given below: + +1. Sign in to the [Choreo Console](https://console.choreo.dev/). +2. In the **Component Listing** pane, click on the component you want to scale-to-zero. +3. Make sure the component is deployed to an environment and is ready to receive traffic. +4. In the left navigation menu, click **K8s Operations** and then click **Scaling**. + + - **If you are a free user**, you will see a view similar to the one below. You can click the **scale-to-zero** card to enable scale-to-zero for your component. + + ![Free User - Scale to Zero](../../assets/img/devops-and-ci-cd/scaling/free-user-scaling-view.png){.cInlineImage-full} + + - **If you are a paid user or you are running your applications in your own private data plane**, you will see a view similar to the one below. You can click the **scale-to-zero** card to enable scale-to-zero for your component. + + ![Paid User - Scale to Zero](../../assets/img/devops-and-ci-cd/scaling/paid-user-scaling-view.png){.cInlineImage-full} + + !!! note + The scale-to-zero service should start within 60 seconds. If it doesn’t, the gateway will timeout the request. + +You can independently scale Choreo components in both the **Development** and **Production** environments. The deployment card indicates the scaling status of each environment. To configure the scale-to-zero feature for a specific environment, click on the **scale-to-zero** link, which redirects to the **K8s Operations** → **Scaling** page. + +![Deploy View - Scale to Zero](../../assets/img/devops-and-ci-cd/scaling/scale-to-zero-in-deploy-view.png){.cInlineImage-full} + +When you turn on the scale-to-zero for your application, the minimum replicas for your app will be set to zero. However, you can still select an appropriate maximum number of replicas. + +## Limitations + +- The scale-to-zero feature currently exclusively supports web applications and HTTP services. TCP and HTTPS services are not supported to be scaled to zero. +- To scale to zero, your HTTP service must run on one of the specified ports: 5000, 6000, 7000, 8000, 9000, 7070 to 7079, 8080 to 8089, and 9090 to 9099 or 8290. If you have an endpoint in your component running in any other port, your component will not automatically scale-to-zero when deploying or promoting. Also, if you try to switch to the “scale-to-zero” option in the “Devops” → “Scaling” view, it will fail. +- Scheduled tasks and manually triggered components cannot connect to a service on a project scope if scale-to-zero is enabled. Attempting to do so results in the following error: + + `Host not found, not forwarding request.` + + To allow a task-type component to invoke a project-level service, set it to HPA mode if you are on a paid plan, or to no scaling if you are on the Developer plan. + +## Architecture + +When your Choreo application scales down to zero, an intermediary proxy service intercepts incoming requests. If a request is directed at your application, this service initiates a scale-up. Requests are held in the proxy's queue until your application becomes active. After scaling up, the proxy forwards the queued requests to your application. + +If your application remains without HTTP traffic for an extended period (default idle time is 5 minutes), it will be scaled down to zero until more HTTP requests arrive. Conversely, if there's a surge in HTTP traffic to your scaled-up application, Choreo will further increase its scale to manage the demand. Choreo considers adding additional replicas if the number of queued requests surpasses the 'Target Pending Requests' threshold, which is set to 100 by default. You can adjust this threshold in the user interface. + +!!! note + The initial request after a long period of inactivity experiences a delay because the application must first scale up from zero. If your API operates in a service-chain sequence (e.g., service-1 activates service-2, which in turn calls service-3), this waiting time may extend further. If your application or its chain takes a considerable time to scale up, be aware that the first request might face a timeout. + +## Troubleshooting + +When Choreo enables scale-to-zero by default, it will configure the readiness probe with some default values. However, in some cases, you may observe that your first request responds with a 503 status code. To overcome these behaviors, fine-tune the readiness probe in the **DevOps** → **Health Checks** view to match your application's needs. diff --git a/en/pe-docs/docs/k8s-operations/set-up-health-checks.md b/en/pe-docs/docs/k8s-operations/set-up-health-checks.md new file mode 100644 index 000000000..fe29926e3 --- /dev/null +++ b/en/pe-docs/docs/k8s-operations/set-up-health-checks.md @@ -0,0 +1,66 @@ +# Set Up Health Checks + +Health checks ensure that a running container is always healthy and ready to serve traffic. + +## Liveness probes + +Liveness probes run periodically on your container and restart if the probe fails. +This allows the container to self-heal in scenarios where the application may have crashed or become unresponsive. + +## Readiness probes + +Similar to liveness probes, readiness probes run periodically throughout the lifecycle of a container. +However, unlike liveness probes, these probes do not restart the container if the probe fails. Instead, they stop the container from receiving network traffic. + +!!! warning "Readiness probes on single replicas" + You must be mindful when you configure readiness probes on a single-running replica. If the readiness probe fails, your application stops receiving traffic because there is only one active replica. The application may not recover unless the liveness probe fails and restarts the container. + +## Probe types + +You can configure the following probe types for both readiness and liveness probes. + +### HTTP `GET` request + +This probe sends an HTTP `GET` request to a specified port and path on the container. A response status code in the range of 200-399 indicates that the request is a success. + +Depending on your requirement, you can configure additional HTTP headers. + +The recommended approach is to create a `/healthz` or `/health` endpoint in your service for this purpose. + +![HTTP GET probe](../assets/img/devops-and-ci-cd/healthchecks/http-get-probe.png){.cInlineImage-half} + +### TCP connection probe + +This probe attempts to open a socket to the container on the specified port. If it cannot establish a TCP connection, it becomes a failure. + +### Execute a command + +This probe executes a given script inside the container. A non-zero return from the command is considered a failure. + +For example, `["cat", "/tmp/healthy"]` is considered healthy if the file `/tmp/healthy` is present. If not, it becomes a failure (non-zero exit code). +In such scenarios, the application is responsible for writing and maintaining this file in the specified location. + +## Configure liveness and readiness probes + +Follow these steps to configure liveness and readiness probes on a container: + +1. Sign in to the [Choreo Console](https://console.choreo.dev/). +2. In the Choreo Console top navigation menu, select the **Organization**, then the **Project** and the relevant **Component**. +3. In the left navigation menu, click **K8s Configurations** and then click **Health Checks**. +4. On the **Health Checks** page, click **+ Create**. +5. Configure the liveness probe depending on your requirement. + + ![Configure probe](../assets/img/devops-and-ci-cd/healthchecks/confgure-probes.png){.cInlineImage-full} + +6. Click **Save**. +7. Configure the readiness probe depending on your requirement. +8. Click **Save**. + + !!!info "Note" + + You can update or remove a probe at any time. + +Follow these steps to ensure that the container works as expected: + +1. In the left navigation menu, click **K8s Configurations** under **DevOps**. +2. On the **Runtime** page, check the details to confirm that the container works as expected. If the container does not start, check the **events and conditions** to see if any of the probes are causing the container to fail. diff --git a/en/pe-docs/docs/k8s-operations/storage/configure-storage.md b/en/pe-docs/docs/k8s-operations/storage/configure-storage.md new file mode 100644 index 000000000..0d742bd27 --- /dev/null +++ b/en/pe-docs/docs/k8s-operations/storage/configure-storage.md @@ -0,0 +1,84 @@ +# Configure Storage + +All components you create in Choreo have a default **read-only file system**, which you cannot access or write to from your applications. + +Volume mounts allow you to create either temporary or persisted writable file system storage locations for your applications. + +## Volume mount types + +| Type | Description | +| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Empty Directory (In-Memory) | A fast, temporary in-memory (tmpfs) storage location. This volume gets erased when you restart or remove the attached container. *Available on all data planes.* | +| Empty Directory (Disk) | A temporary storage location on disk. This volume gets destroyed when you restart or remove the attached container. *Only available on private data planes.* | +| Persistent Volume | A permanent storage location. This volume persists even if you restart or remove the attached container. *Only available on private data planes.* | + +!!! tip + All components have a writable location in the `/tmp` directory at the time of component creation. You can also configure other writable locations if required. + + +## Create a temporary storage space for your container + +Empty directory (in-memory or on-disk) mounts allow you to create temporary file systems that your application can read from and write to. This option provides a convenient way to create a *scratch space* to write files temporarily before storing them in a more permanent storage location such as a cloud-backed storage bucket. +For example, unzipping a file, temporarily writing results from a memory-intensive operation to disk, a temporary local cache, etc. +However, it is important to note that these volumes destroy when you restart or update a container because the volumes are attached to the lifetime of a container. + +Follow these steps to create a temporary storage space for your container: + +1. Sign in to the [Choreo Console](https://console.choreo.dev/). +2. In the Choreo Console top navigation menu, select the **Organization**, then the **Project** and the relevant **Component**. +3. In the left navigation menu, click **K8s Operations** and then click **Storage**. +4. Click **+ Create**. +5. In the **Create a Volume Mount** pane, specify a name for the volume and select **Empty Directory (In-Memory)**. + + ![Create temporary storage](../../assets/img/devops-and-ci-cd/storage/create-emptydir-step-1.png){.cInlineImage-full} + +6. Click **Next**. + + !!! warning "In-memory (tmpfs) storage uses up container memory" + Storage capacity for this type of volume will count against the container's memory limit.
+ Uncontrolled writes to this location may starve your application process of memory and can result in the container getting killed and restarted if the memory limits exceed. + +7. To add a mount location, specify a **Mount Path** and click **Add mount**. + + !!!tip + + - You can add multiple mount locations to a volume. + - Mount paths should be *absolute file paths* and will be available to your application to read/write from. + + ![Specify mount details](../../assets/img/devops-and-ci-cd/storage/create-emptydir-step-2.png){.cInlineImage-full} + +8. Click **Create**. This applies the volume mount immediately to your container and triggers a rolling restart. + +## Create a persistent storage space for your container + +Follow these steps to create a persistent storage space for your container: + +!!! info "Note" + + Persistent volume options are only available in private data plane organizations. + + +1. Sign in to the [Choreo Console](https://console.choreo.dev/). +2. In the Choreo Console top navigation menu, select the **Organization**, then the **Project** and the relevant **Component**. +3. In the left navigation menu, click **K8s Operations** and then click **Storage**. +4. Click **+ Create**. +5. In the **Create a Volume Mount** pane, specify a name for the volume and select **Persistent Volume**. +6. Select a **Storage Class**. +7. Move the **Storage Capacity** slider to set the required capacity. +8. Select an appropriate **Access Mode**. + + !!! tip "Check and specify an access mode supported by the storage class" + - You must check the cloud provider documentation to select an appropriate access mode that the storage class supports. Choreo does not verify whether the storage class supports the access mode you select. + - If the storage class does not support the access mode you select, it can result in a runtime mount error. + + ![Create persistent storage](../../assets/img/devops-and-ci-cd/storage/create-pv.png){.cInlineImage-full} + +9. Click **Next**. +10. To add a mount location, specify a **Mount Path** and click **Add mount**. + + !!!tip + + - You can add multiple mount locations to a volume. + - Mount paths should be *absolute file paths* and will be available to your application to read/write from. + +11. Click **Create**. This applies the volume immediately to your container. diff --git a/en/pe-docs/docs/observability/alerts/configure-alerts.md b/en/pe-docs/docs/observability/alerts/configure-alerts.md new file mode 100644 index 000000000..59e5e17ca --- /dev/null +++ b/en/pe-docs/docs/observability/alerts/configure-alerts.md @@ -0,0 +1,141 @@ +# Configure Alerts + +This section explains how you can configure alerts for your Choreo components. Setting up alerts allows you to proactively monitor your components ecosystem and take corrective measures when necessary. + +!!! tip + Setting up alerts in only available in the component level. + +## Alert Types + +Choreo supports the following types of alerts to help you monitor and manage your components effectively: + +- [Latency alerts](#latency-alerts) +- [Traffic alerts](#traffic-alerts) +- [Resource alerts](#resource-alerts) +- [Log alerts](#log-alerts) +- [Build failure alerts](#build-failure-alerts) +- [Status code alerts](#status-code-alerts) + +### Latency Alerts + +Latency alerts notify you if the response latency of a component exceeds a predefined threshold in a given time period. This is useful for components that need to meet specific SLAs and for proactively identifying slow components. + +Configurable parameters + +| **Parameter** | **Description** | +|---------------|---------------------------------------------------------------------------------| +| Metric | 99th, 95th, 90th, or 50th percentile. | +| Threshold | Latency in milliseconds (e.g.: 1800). | +| Period | Duration the threshold must be exceeded (e.g.: 5 minutes). | + +### Traffic Alerts + +Traffic alerts notify you when the request count of a component exceeds a predefined threshold. This is useful for managing components with backend traffic limits or monetized backends that require proactive scaling based on incoming traffic. + +Configurable parameters + +| **Parameter** | **Description** | +|---------------|---------------------------------------------------------------------------------| +| Threshold | Requests per minute (e.g.: 200). | +| Period | Monitoring window (e.g.: 5 minutes). | + +### Resource Alerts + +Resource alerts notify you when your component’s CPU or memory usage exceeds the defined thresholds. This ensures you can fix the resources allocations early to avoid performance issues or downtimes. + +Configurable parameters + +| **Parameter** | **Description** | +|---------------|---------------------------------------------------------------------------------| +| Metric | CPU or Memory. | +| Threshold | **mCPU** for CPU and **MiB** for Memory(e.g.: 1000). | +| Period | Duration the threshold must be exceeded (e.g.: 5 minutes). | + +!!! Tip + - **CPU**: mCPU (milliCPU) measures CPU usage in fractions of a core, where 1000m = 1 full core. + - **Memory**: MiB (Mebibyte) measures memory in binary units, where 1 MiB = 2^20^ bytes. + +### Log Alerts + +Log alerts trigger notifications when a specific phrase appears **a specific number of times** in your component logs within a defined Time window. This helps to identify recurring issues or critical errors quickly, enabling faster troubleshooting. + +Configurable parameters + +| **Parameter** | **Description** | +|---------------|---------------------------------------------------------------------------------| +| Search Phrase | Keyword or phrase to look for to trigger the alert (e.g.: failed). | +| Count | Minimum number of occurrences to trigger the alert (e.g.: 10). | +| Interval | Time window for counting occurrences (e.g.: 5 minutes). | + +### Build Failure Alerts + +Build failure alerts inform you if a build failure occurs for your component. This is essential for maintaining smooth development workflows. + +### Status Code Alerts + +Status code alert triggers when your component returns specific HTTP error(s) (e.g.: **403** Forbidden, **500** Internal Error). These alerts help to detect issues affecting your component’s availability. + +Configurable parameters + +| **Parameter** | **Description** | +|---------------|---------------------------------------------------------------------------------| +| Status Code | Error code or series (e.g.: 400:Bad Request). | +| Count | Minimum number of occurrences (e.g.: 5). | +| Interval | Time window (e.g.: 5 minutes). | + +!!! note + Status code alerts are only supported for API proxy component types. + +## Configure Alert + +Follow these steps to configure an alert: + +1. Navigate to the component you wish to configure alerts for. + + !!! info + You need to have a scope of **Choreo DevOps** or **Choreo Platform Engineer** inorder to create Alerts. + +2. In the Choreo left menu, click **Observability** and then click **Alerts**. +3. Click **Create Alert Rule** to create a new alert rule. + + ![Create Alert Rule](../../assets/img/monitoring-and-insights/alerts/alert-creation.png){.cInlineImage-full} + +4. Select the **[Alert Type](#alert-types)** you want to create. +5. Select the **Environment** you want to create the alert for. +6. Select the **Deployment Track** or **Version** as required for the component. +7. Configure the remaining fields specific to your selected alert type. +8. In the **Emails** field, specify the list of emails that should be notified when the alert is triggered. + + !!! note + - When adding an email, enter the required email and press enter to add it. + - You can add a maximum of 5 email addresses per alert. + +9. You can configure additional parameters in **Advanced Configurations** dropdown as needed, which vary based on your alert type. +10. The **Explanation window** provides a concise summary of the configured alert based on your alert configurations. +11. Click **Create** to save and activate your alert rule. + + !!! info + - You can configure a maximum of 10 alerts per component. + +12. Once successfully added, your alert will be listed in the **Configure Alerts** pane alongside any existing alerts for the component. +13. Each alert can be **edited**, **removed** and **disabled** or **enabled** via this pane. + + !!! note + when editing an alert, you can't edit the **Alert Type**, **Environment** and **Deployment Track**. + +## Alert History & Notifications + +### View Alert History + +You can check the past alerts that have triggered for your component when you click the **Alerts History** pane in Choreo Alerts. You can filter the alert history by **Alert Type**, **Environment**, **Deployment Track** or **Version** and **Time Range**. + +!!! note + When filtering, **API Proxy components** show a **Version** filter and other components display a **Deployment Track** filter, based on their monitoring context. + +You can click on an alert to expand it and see more details of the triggered alert. + +### Email Notifications + +When an alert is triggered, **recipients** added to the alert rule receive an email with **alert details** including a direct **Alert View link** to Choreo console. + +![Email Notification](../../assets/img/monitoring-and-insights/alerts/email-notification.png){.cInlineImage-full} diff --git a/en/pe-docs/docs/observability/audit-logs.md b/en/pe-docs/docs/observability/audit-logs.md new file mode 100644 index 000000000..32fd54358 --- /dev/null +++ b/en/pe-docs/docs/observability/audit-logs.md @@ -0,0 +1,64 @@ +# Audit Logs in Choreo + +Audit logs, also called audit trails, enhance security, ensure compliance, provide operational insights, and help manage risks. + +In Choreo, an audit log records organization-level user-specific operations performed via the Choreo Console. It also captures the timestamp and the outcome of the action. + +As of now, Choreo captures the following user-specific operations as audit logs: + +- Project creation, update, and deletion. +- Component creation, update, and deletion. +- Component promotion initiation. +- Component version creation. +- Component deployment, redeployment, and undeployment initiation for all components other than REST API Proxy components. +- Component API access mode update. +- Enabling and disabling component auto-deployment on commit. +- Component build configuration update. +- Component endpoint creation, update, and deletion. +- Organization user management. +- On-premises key management. +- Project-level configuration management. + +In Choreo, organization administrators and platform engineers are allowed to view audit logs by default. If other members need to access organization-specific audit logs, the administrator or the platform engineer can create a role with the relevant permission and assign it to members. For step-by-step instructions on how to create and assign a role with relevant permission, see [Manage audit log access](#manage-audit-log-access). + +To view audit logs, follow these steps: + +1. Sign in to [Choreo](https://console.choreo.dev/). +2. In the top navigation menu, click the **Organization** list and select your organization. + + !!! tip + As of now, you can only view organization-level audit logs. + +3. In the left navigation menu, click **Observability** and then click **Audit Logs**. This displays audit logs for the past 24 hours by default. + + To view audit logs based on a specific time range and other requirements, you can apply the necessary filter criteria. + + ![Audit logs](../assets/img/monitoring-and-insights/view-logs/audit-logs.png) + +### Audit log retention + +Choreo retains audit logs for one year and archives them for an additional year. Therefore, the total retention period for audit logs is two years. + +### Manage audit log access + +Follow the steps given below to create a role with audit log access permission and assign it to organization members who need access to audit logs: + +!!! info "Note" + You must be the organization administrator or a platform engineer to perform this action. + +#### Step 1: Create a role with audit log access permission + +1. In the top navigation menu, click the **Organization** list and select your organization. +2. In the left navigation menu, click **User Management** and then click **Roles**. +3. On the **Roles** page, click **+ Create Role**. +4. Enter a name and description for the role. +5. In the **Permissions** section, select **LOG-MANAGEMENT** to grant permission to view audit logs. +6. Click **Create**. + +#### Step 2: Assign the created role to a group and organization member +1. In the left navigation menu, click **User Management** and then click **Groups**. +2. On the **Groups** page, click **+ Create Group**. +3. Enter a name and description for the group and then click **Create**. +4. Locate and click on the newly created group in the list. +5. Navigate to the Roles tab, click **+ Add Role**, and choose the role you created in [Step 1](#step-1-create-a-role-with-audit-log-access-permission). +6. In the Users tab, click **+ Add User** and select the users to assign the role to. diff --git a/en/pe-docs/docs/observability/private-data-plane-logs.md b/en/pe-docs/docs/observability/private-data-plane-logs.md new file mode 100644 index 000000000..f9fc3bc4a --- /dev/null +++ b/en/pe-docs/docs/observability/private-data-plane-logs.md @@ -0,0 +1,70 @@ +# Private Data Plane (PDP) Logs + +Choreo offers the capability to access runtime logs through its console. However, in cases where viewing logs for your PDP is not supported by Choreo yet, you can still view the runtime logs of your components via the log analyzing solution provided by your cloud vendor as a workaround. + +## Prerequisites + +Before you try out this guide, complete the following: + +1. In the Choreo Console top navigation menu, select the **Organization**, then the **Project** and finally the relevant **Component** for which the incident was reported. +2. On the left navigation menu, click **K8s Operations** and then click on **Runtime**. +3. Copy the `Release ID` and the `Namespace`. Save it for later. + +## View Private Data Plane (PDP) logs with Azure Log Analytics + +You can view your PDP logs with Azure Log Analytics by following the steps below: + +1. Go to https://portal.azure.com/. +2. Follow the [Azure Log Analytics Tutorial](https://learn.microsoft.com/en-us/azure/azure-monitor/logs/log-analytics-tutorial#open-log-analytics) and open log analytics of your relative log analytics workspace. +3. Copy and paste the query below into the query editor. +4. Replace the `` and `` values as required. Replace the `` and `` with the values you copied by following the steps in the [prerequisites](#prerequisites) section. Replace the `` with your search term, or leave it blank if you don't require any search filtering. +5. Run the query to extract the relevant logs. + +```SQL +let startDateTime = datetime(''); +let endDateTime = datetime(''); +let releaseId = ''; +let namespace = ''; +let searchPhrase = ''; +let startDateTimeKPI = iff(datetime_diff('second', endDateTime, startDateTime) > 60, startDateTime, endDateTime - 2m);let endDateTimeKPI = iff(datetime_diff('second', endDateTime, startDateTime) > 60, endDateTime, startDateTime + 2m);let filteredLogLevels = dynamic([]); +let hasNoLevelFilter = array_length(filteredLogLevels) == 0; +let commonKeys = dynamic(['time', 'level', 'module', 'traceId', 'spanId', 'message']); +let ContainerIdList = KubePodInventory +| where TimeGenerated > startDateTimeKPI and TimeGenerated < endDateTimeKPI +| where Namespace == namespace +| where extractjson('$.[0].release_id', PodLabel) == releaseId +| distinct ContainerID; +let data = ContainerLog +| where TimeGenerated > startDateTime and TimeGenerated < endDateTime +| where ContainerID in (ContainerIdList) +| where searchPhrase == "" or LogEntry contains searchPhrase +| top 126 by TimeGenerated desc +| extend logs = parse_json(LogEntry) +| project TimeGenerated, +LogLevel = iif(isempty(logs['level']), iff(LogEntrySource == 'stderr', 'ERROR', 'INFO'), logs['level']), +LogEntry = iif(isempty(logs['message']), logs, logs['message']), +KeyValuePair = bag_remove_keys(logs, commonKeys) +| where hasNoLevelFilter or LogLevel in (filteredLogLevels); +let lastTimeStamp = data +| top 1 by TimeGenerated asc | project TimeGenerated; +let trimmedData = data | where TimeGenerated > toscalar(lastTimeStamp)| sort by TimeGenerated desc; +let selected = iff(toscalar(data | count) == 126, 'trimmedData', 'data'); +let choose = (selector:string){ union (trimmedData | where selector == 'trimmedData'), (data | where selector == 'data')}; +choose(selected); +``` + +## View Private Data Plane (PDP) logs with Amazon CloudWatch + +1. Go to https://portal.azure.com/. +2. Follow the [AWS Analyzing Log Data documentation](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/AnalyzingLogData.html) and open **Log Insights**. +3. Select the relevant region and the relevant log group (the log group string has the cluster name and “/application” appended at the end). +4. Select the required time range. +4. Copy the query below and paste it into the query editor. +5. Replace the `` with the values you copied by following the steps in the [prerequisites](#prerequisites) section. Replace the `` with your search term, or leave it blank if you don't require any search filtering. +6. Run the query to extract the logs. + +``` SQL +fields @timestamp, @message +| filter kubernetes.labels.release_id == "" +| filter @message like "" +``` diff --git a/en/pe-docs/docs/observability/runtime-logs.md b/en/pe-docs/docs/observability/runtime-logs.md new file mode 100644 index 000000000..0384ba542 --- /dev/null +++ b/en/pe-docs/docs/observability/runtime-logs.md @@ -0,0 +1,58 @@ +# Runtime Logs in Choreo + +Choreo runtime logs provide insights into both project and component-level logs, covering application and gateway logs. These logs streamline the debugging process by centralizing diverse log sources. + +In Choreo, any organization member can view runtime logs via the runtime logs page. Choreo allows you to apply filters based on parameters such as log level (error, warn, info, debug), log type (application, gateway), and environment (development, staging, production) to simplify the debugging process. + +To access runtime logs, follow the steps below: + +1. Sign in to [Choreo](https://console.choreo.dev/). +2. In the left navigation menu, click **Observability** and then click **Runtime Logs**. This displays runtime logs for the past 24 hours by default. + + To view logs based on a specific time range and other requirements, you can apply the necessary filter criteria. + + ![Runtime logs](../assets/img/monitoring-and-insights/view-logs/runtime-logs.png) + +### Understand runtime logs + +When you view component-level logs on the **Runtime Logs** page, you will see both application and gateway logs. + +#### Application logs + +Each application log entry displays the following details: + + - `timestamp`: The time when the request is received by the component. + - `level`: Indicates the severity of the log message. Possible values are **Debug**, **Info**, **Warn**, and **Error**. + - `componentVersion`: The version of the invoked component. + - `componentVersionId`: The identifier of the invoked component’s version. + - `envName`: The environment of the inbound request. For example, Development, Production, etc. + +#### Gateway logs + +Each gateway log entry displays the following details: + + - `timestamp`: The time when the request is received by the gateway component. + - `logLine`: Contains the following details about the request, including inbound and outbound information from the gateway perspective. + - `Method`: The HTTP method of the request. + - `RequestPath`: The path of the inbound request. + - `ServicePath`: The path of the outbound request. + - `UserAgent`: The user-agent header of the request. + - `CorrelationID`: The request identifier of the inbound request. This is useful to track a request. + - `ServiceHost`: The host IP of the backend. + - `Duration`: The time taken for the gateway to serve the request.   + - `gatewayCode`: Indicates the state of the request from the gateway perspective. Possible values are as follows: + - `BACKEND_RESPONSE`: Indicates successful processing of the request by the gateway with a response to the client from the backend application. + - `CORS_RESPONSE`: Denotes a CORS (Cross Origin Resource Sharing) request. + - `AUTH_FAILURE`: Indicates a request failure at the gateway due to authentication or authorization issues, such as an invalid token. + - `NO_HEALTHY_BACKEND`: Indicates a request failure at the gateway due to a non-existent backend. + - `RATE_LIMITED`: Indicates a request failure at the gateway due to surpassing the rate limit enforced within the component. + - `RESOURCE_NOT_FOUND`: Indicates a request failure at the gateway due to the absence of a matching API resource for the inbound request. This can be caused by a mismatch in the HTTP method, path, or host. + - `BACKEND_TIMEOUT`: Indicates a request timeout when calling the backend application from the gateway. + - `GATEWAY_ERROR`: Indicates a request failure due to an erroneous behavior in the gateway. + + !!! info "Note" + Occasionally, a request may not fit into any of the above categories. In such instances, the `gatewayCode` is displayed as `UNKNOWN`. + + - `statusCode`: The HTTP status code returned to the client. + - `componentVersion`: The version of the invoked component. + - `envName`: The environment of the inbound request. For example, Development, Production, etc. diff --git a/en/pe-docs/docs/overview.md b/en/pe-docs/docs/overview.md new file mode 100644 index 000000000..9cc9290d8 --- /dev/null +++ b/en/pe-docs/docs/overview.md @@ -0,0 +1,3 @@ +#### Overview + +PE view diff --git a/en/pe-docs/docs/page-not-found.md b/en/pe-docs/docs/page-not-found.md new file mode 100644 index 000000000..063cf21b1 --- /dev/null +++ b/en/pe-docs/docs/page-not-found.md @@ -0,0 +1,21 @@ + + + +Try one of the navigation links above or use the search engine in the top right corner.  + diff --git a/en/pe-docs/docs/references/choreo-limitations.md b/en/pe-docs/docs/references/choreo-limitations.md new file mode 100644 index 000000000..bf9fd029d --- /dev/null +++ b/en/pe-docs/docs/references/choreo-limitations.md @@ -0,0 +1,31 @@ +# Choreo Limitations + +Explore key limitations in Choreo, covering areas like HTTP request parameters, components, applications, and API definition files. You can gain insights into the limitations to enhance your understanding and optimize your use of Choreo effectively. + +## API management limits + +Below are key limitations when working with APIs in Choreo: + +|Resource | Limit | +|-------------------------------------|---------------------------------------------------------------------------------------------| +| Maximum request payload | 50 MB | +| URL size | 2 KB | +| Request header |
  • Request Headers total: 40 KB
  • Max Single Request header: 10 KB
| +| Total request duration |
  • Minimum: 10 seconds
  • Default: 1 minute
  • Maximum: 5 minutes
| +| Maximum connection duration (WebSocket APIs) | 15 minutes | +| Connection idle timeout (WebSocket APIs) | 5 minutes | +| Size for API definition (OpenAPI document)| 10 Mb | +| Number of APIs for PDP | 1000 API deployments | +| Number of APIs per organization (free tier) | 5 APIs for free users | +| Number of Developer Portal applications per organization (free tier) | 10 applications for free users | + + +## Choreo cloud data plane limits + +Below are key limitations when working with web applications in the Choreo cloud data plane: + +| Resource | Limit | +|------------------------------------|---------------------------------------------------------------------------------------------| +| Request size limit (including headers, cookies, and payloads) | 256 KB | +| Response body size limit | 20 MB | +| Number of open ports permitted per web application| 1
While it is possible to have multiple ports open for project-level communication within a data plane, incoming internet traffic can only be directed to a single port. This contrasts with Service-type components, which allow for multiple endpoints.| diff --git a/en/pe-docs/docs/references/choreo-platform-services-billing-and-upgrades.md b/en/pe-docs/docs/references/choreo-platform-services-billing-and-upgrades.md new file mode 100644 index 000000000..642397ec1 --- /dev/null +++ b/en/pe-docs/docs/references/choreo-platform-services-billing-and-upgrades.md @@ -0,0 +1,12 @@ +# Choreo Platform Service Billing and Upgrades + +Choreo bills the platform services you create, such as databases, caches, or Kafka services, as part of your existing subscription. The cost depends on the service plan and the usage of each resource. + +## Platform service billing information + +- **Hourly billing**: Usage is billed based on the number of hours a resource is active. For example, if you create a database, cache, or Kafka service and remove it within the same month, you pay only for the hours it was active. +- **Fixed pricing**: Pricing is based on the selected service plan. Choreo does not charge extra for network bandwidth usage. + +## Upgrade a service plan + +If you want to upgrade the service plan of a platform service you have created, contact [Choreo support](mailto:choreo-support@wso2.com). diff --git a/en/pe-docs/docs/references/faq.md b/en/pe-docs/docs/references/faq.md new file mode 100644 index 000000000..c0246e1ae --- /dev/null +++ b/en/pe-docs/docs/references/faq.md @@ -0,0 +1,620 @@ +# Frequently Asked Questions + +## General + +### Q: What is Choreo? +Choreo is an internal developer platform designed to accelerate the creation of digital experiences. With Choreo, you can effortlessly build, deploy, monitor, and manage your cloud native applications. Our goal is to enhance developer productivity and enable innovation. + +### Q: What is an organization in Choreo? +An organization is a logical grouping of users and their resources. It may represent a company, community, or a single user. Users can belong to multiple organizations, and each organization can have different roles assigned to its users to control access to Choreo features. + +### Q: What is a project in Choreo? +A project is a logical grouping of related components to help you organize your work. Each project provides runtime isolation through namespaces when you deploy components. + +### Q: What is a component in Choreo? +A component is a workload designed to run on Choreo. Examples of components include integrations, APIs, microservices, manual/scheduled jobs, web apps, and triggers. + +### Q: What is the difference between an internal and external API? +In Choreo, you can publish an API as an internal or an external API. A user or an application can access an external API publicly over the internet, whereas an internal API is only accessible through other components within the same organization. + +### Q: What is a connector in Choreo Marketplace? +A connector is a reusable Ballerina package that simplifies connecting to external or internal systems and APIs, such as Salesforce, SAP, GitHub, and Twilio. You can use the connectors available in the Choreo marketplace to implement your integration use cases. Connectors can be created and published by both WSO2 and Choreo users. + +### Q: What is a trigger in Choreo Marketplace? +A trigger is a construct that enables users to receive known event payloads from external systems, facilitating event-driven programming. + +### Q: What is a sample/template in Choreo? +A sample or template is a prebuilt Ballerina program that covers a popular integration use case or pattern. Examples include connecting Salesforce to Slack or implementing content-based routing. + +### Q: What are the support options in Choreo? +You can find information about our support plans, including `free`, `basic`, and `enterprise` options at [https://wso2.com/choreo/customer-support/](https://wso2.com/choreo/customer-support/). + +### Q: How can I perform log monitoring or analytics for the Azure environment? +If you have a log monitoring product or service, such as Azure Monitor, you can use it together with Choreo. Note: The log monitoring tool is not included in the infrastructure cost. + +### Q: What is the maximum request payload size supported by Choreo? +Choreo allows a maximum request payload size of 50 MB. + +### Q: What source control software does Choreo support? +Choreo now supports GitHub, Bitbucket and GitLab. + +### Q: Why don't I see the undeployed builds for my component in Choreo? +You are allowed to build your component any number of times. However, Choreo has a limit on retaining undeployed builds. For users on the free-tier, Choreo will retain **only one** undeployed build. For those on any other tier, Choreo will retain the **latest five** undeployed builds. + +### Q: What is Ballerina? +Ballerina is an open-source programming language designed for the cloud. It simplifies the process of using, combining, and creating network services. When you use Ballerina to write integrations in Choreo, you can save time and deliver 2-3x faster. To learn more, check out https://ballerina.io/. + +### Q: What is Asgardeo? +Asgardeo is an identity provider (IdP) that allows developers to secure access for consumers, business partners, employees, and APIs. Asgardeo is Choreo’s default IDP. To learn more, visit https://wso2.com/asgardeo/. + +### Q: Why don’t I see the region selector on the project creation page? +If you are a Choreo cloud data plane user, you can create projects in multiple regions only if you have a paid subscription in Choreo. Otherwise, your projects will be created in the same region you selected when onboarding the organization. + +If you are a private data plane user, there will be no region selector in project creation at all. + +### Q: As a Cloud Data Plane user, how can I create components in multiple data planes? +When an organization admin onboards a new organization in Choreo, they can choose the preferred data plane. Choreo then sets the selected data plane as the default for the entire organization. Subsequently, users within the free tier of the cloud data plane can create components only in the set default data plane. If a free-tier user needs to create components in a different data plane, the user must get a paid subscription. + +## Security and data protection + +### Q: How is data managed in Choreo? +Choreo manages data using WSO2 containers and Kubernetes clusters, which provide scalability, resilience, and security. Find out more [here](https://wso2.cachefly.net/wso2/sites/all/trust/wso2-public-cloud-data-protection-faq.pdf). + +### Q: What is the WSO2 Subprocessor list? +This is a detailed list of all subprocessors used by WSO2, including their name, location, and purpose. This information is updated frequently to ensure compliance with data protection regulations and is found [here](https://wso2.cachefly.net/wso2/sites/all/trust/wso2-public-cloud-subprocessor-list.pdf). + +### Q: How do we secure WSO2 Private and Public Clouds? +WSO2 uses a range of security controls and design patterns to protect against several threats, including internal attacks, software supply chain attacks, service and platform attacks, and more. For more details, see[Cloud Security Process](https://security.docs.wso2.com/en/latest/security-processes/cloud-security-process/). + +### Q: How can I connect a Choreo component with a protected third-party application? +To connect a Choreo component with a third-party application, it is necessary to establish seamless communication between the component and the protected third-party application, especially when connecting to external databases like MySQL, MSSQL, PGSQL, Oracle DB, etc. +To ensure this, the requests coming from the Choreo data plane must be allowed by adding the specific data plane IP ranges to your allowlist. + +- If your component is deployed in the Choreo US data plane, add the following IP range to your allowlist: + - 20.22.170.144/28 + +- If your component is deployed in the Choreo EU data plane, add the following IP range to your allowlist: + - 20.166.183.112/28 + +- If you are working on the [Cybertruck Challenge](https://wso2.com/cybertruck/), add the following IP range to your allowlist: + - 20.190.30.48/28 + +## Data planes + +### Q: What is a Choreo control plane? +The Choreo control plane is a centralized management component that oversees and coordinates the workloads deployed by customers. It provides a unified point of control and visibility for the organization, allowing administrators to manage, monitor, and orchestrate the organization’s resources efficiently. + +### Q: What is a data plane? +A data plane in Choreo is a computing environment designed for running customer workloads. These environments are hosted in either a dedicated cloud infrastructure owned by the customer (private data planes) or on public cloud infrastructure owned by WSO2, also known as the Choreo data plane. + +### Q: Which regions support the Choreo data plane(CDP)? +The Choreo data plane is currently supported in the US East 2 and North Europe. However, WSO2 is planning to add support for additional regions as needed. + +### Q: Which regions support private data planes(PDPs)? +Private data planes can be deployed in any region where Azure and AWS are available and meet the requirements for PDPs. + +### Q: If I want to use my Azure AKS instances as the private data plane, what are the minimum requirements I should meet? +We recommend using a minimum of two (2) workload nodes to ensure high availability. + +### Q: Are the Choreo control plane and data planes highly available? Are they running on multiple clusters? +The Choreo control plane and data plane are designed for high availability using Azure components like AKS, MSSQL, ACR, KV, Service Bus, and so on, with a high availability of 99.99%, which allows at least three workload nodes. In the event of a node failure or upgrade, this setup provides reliable failover. WSO2 also has a backup and recovery strategy in place, including continuous restore drills. If you require AKS cluster-level redundancy, we can consider multiple zones. In this case, the cost will include an additional infrastructure cost. + +## Environments + +### Q: As a Choreo cloud data plane user, why can't I create environments? +You can create environments only if you have a paid subscription in Choreo. It can be either Pay-as-you-Go (PAYG) or an Enterprise plan. + +### Q: I am a Pay-As-You-Go (PAYG) customer using the Choreo cloud data plane. How many environments can I create? +You can create up to 5 environments at the organization level, including the existing Development & Production environments by default. If you have projects in both data planes (US & EU), there will be 4 environments already created in total, and you will only be allowed to create one additional environment either in the US or EU data plane. + +### Q: I am an Enterprise subscription customer using the Choreo private data plane. How many environments do I get? +As an Enterprise subscription customer, the number of environments you can use is **not** limited. However, the more environments you use, the more resources you will consume in the data plane for the workload you deploy. This may result in higher infrastructure costs for the private data plane. + +### Q: As a Choreo cloud data plane user, why don’t I see both US & EU data planes in the data plane selector when creating an environment? +You will see both US & EU data planes only if you have a paid subscription and have created projects in both US & EU data planes. + +### Q: I am a customer who use Choreo in a private data plane. How many environments can I create? +Initially, you will receive the requested number of environments when establishing your private data plane. Subsequently, you can create additional environments as needed. + +## Billing and support + +### Q: Whom do I reach out to if I have a billing question? +You can reach out to cloud-billing-support@wso2.com or create a support ticket via our support portal. + +### Q: What's a Developer plan? +A Developer plan allows you to try out Choreo’s capabilities at no cost. It’s ideal for proof of concept (PoC) tasks or workloads with limited transactions. This plan allows you to experiment with up to 5 components and provides US$1,000/year of Choreo data plane (CDP) credits. + +### Q: How do I calculate the infrastructure costs? +Calculating infrastructure costs depends on the type of workload you want to manage. Here are a few examples: + +- **Example 1**: Managing existing APIs as an API proxy with simple mediation; no additional infrastructure costs. +- **Example 2**: Managing existing APIs as an API proxy with complex mediation and policies; Choreo will deploy 1 x container to handle these mediation and policies at approximately US$57.25 per month per API. +- **Example 3**: Creating, deploying, and managing a new API or integration within Choreo; pay for 1 x component + infrastructure cost. Each container deployed will be approximately US$57.25 per month on the default configuration provided by Choreo. Additional resources will be charged based on the type of resource required. +- **Example 4**: Creating, deploying, and managing a microservice; the same approach as example 3. + +### Q: What are the component limitations? + +- **Developer plan**: Allows up to a maximum of five free components and unlimited paid components. +- **PAYG plan**: Allows unlimited paid components. +- **Enterprise plan**: Allows unlimited paid components. + +### Q: How do I read the bill? +Your bill will detail the number of components used, infrastructure consumed, support plans used, and any additional services you may have purchased. If you are unsure about any charges on your bill, reach out to choreo-support@wso2.com for clarification. + +### Q: Is support included in the Choreo Enterprise plan? +The Choreo Enterprise plan does not automatically include support; however, you can purchase support plans in addition to the Enterprise plan at any time. Find out more at https://wso2.com/choreo/customer-support/. + +### Q: I am an Enterprise subscription customer who wants to use the Choreo private data plane. What costs will I incur in addition to the subscription and support plan? +You can start by using a basic plan or contact us for an Enterprise support plan. + +### Q: I want to upgrade from PAYG to an Enterprise subscription. Will there be an outage during the upgrade? +No, there are no outages when upgrading a plan. + +## Choreo CLI + +### Q: How do I uninstall the CLI? +If you didn't download the binary directly, you can uninstall the CLI by deleting the `.choreo` directory in the +home directory of your operating system. + +### Q: How do I update the CLI? +You can update the CLI by running the following command: +```sh +curl -o- https://cli.choreo.dev/install.sh | bash +``` + +### Q: What are the supported component types in the CLI? +The Choreo CLI currently supports the following component types: +- Service +- Web Application +- Webhook +- Scheduled Task +- Manual Task + +### Q: How do I get help with a specific command in the CLI? +You can get help with a specific command by running the following command: +```sh +choreo --help +``` + +### Q: What are the build configurations required when creating components using the CLI? +You can configure the component build configurations depending on the component type as follows: + +```sh +choreo create component --project --build-configs='key1=value1,key2=value2' +choreo create component --project --build-configs='key1=value1' --build-configs='key2=value2' +``` + +The build configurations required for existing buildpacks are as follows: + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Component TypeBuildpackRequired Configurations
ServicePython +
    +
  • buildPackLangVersion: Language Version
    • +
+
Node.js +
    +
  • buildPackLangVersion: Language Version
    • +
+
Java +
    +
  • buildPackLangVersion: Language Version
    • +
+
Go +
    +
  • buildPackLangVersion: Language Version
    • +
+
PHP +
    +
  • buildPackLangVersion: Language Version
    • +
+
Ruby +
    +
  • buildPackLangVersion: Language Version
    • +
+
Docker +
    +
  • dockerFilePath: Path to the docker file
    • +
+
Ballerina +
    +
  • Not Applicable
    • +
      +
WSO2 MI +
    +
  • Not Applicable
    • +
      +
.Net +
    +
  • buildPackLangVersion: Language Version
    • +
      +
WebappPython +
    +
  • buildPackLangVersion: Language Version
    • +
  • port: Port
    • +
+
Node.js +
    +
  • buildPackLangVersion: Language Version
    • +
  • port: Port
    • +
+
Go +
    +
  • buildPackLangVersion: Language Version
    • +
  • port: Port
    • +
+
PHP +
    +
  • buildPackLangVersion: Language Version
    • +
  • port: Port
    • +
+
Ruby +
    +
  • buildPackLangVersion: Language Version
    • +
  • port: Port
    • +
+
.Net +
    +
  • buildPackLangVersion: Language Version
    • +
  • port: Port
    • +
+
Docker +
    +
  • dockerFilePath: Path to the docker file
    • +
  • port: Port
    • +
+
Static website +
    +
  • Not Applicable
    • +
      +
React +
    +
  • buildCommand: Command to be used for building the component
    • +
  • outputDirectory: Output directory for the component build artifacts
    • +
  • nodeVersion: Node.js version used
    • +
+
Angular +
    +
  • buildCommand: Command to be used for building the component
    • +
  • outputDirectory: Output directory for the component build artifacts
    • +
  • nodeVersion: Node.js version used
    • +
+
Vue +
    +
  • buildCommand: Command to be used for building the component
    • +
  • outputDirectory: Output directory for the component build artifacts
    • +
  • nodeVersion: Node.js version used
    • +
+
WebhookPython +
    +
  • buildPackLangVersion: Language Version
    • +
+
Node.js +
    +
  • buildPackLangVersion: Language Version
    • +
+
Java +
    +
  • buildPackLangVersion: Language Version
    • +
+
Go +
    +
  • buildPackLangVersion: Language Version
    • +
+
PHP +
    +
  • buildPackLangVersion: Language Version
    • +
+
Ruby +
    +
  • buildPackLangVersion: Language Version
    • +
+
Docker +
    +
  • dockerFilePath: Path to the docker file
    • +
+
Ballerina +
    +
  • Not Applicable
    • +
      +
WSO2 MI +
    +
  • Not Applicable
    • +
      +
Scheduled TaskPython +
    +
  • buildPackLangVersion: Language Version
    • +
+
Node.js +
    +
  • buildPackLangVersion: Language Version
    • +
+
Java +
    +
  • buildPackLangVersion: Language Version
    • +
+
Go +
    +
  • buildPackLangVersion: Language Version
    • +
+
.Net +
    +
  • buildPackLangVersion: Language Version
    • +
+
PHP +
    +
  • buildPackLangVersion: Language Version
    • +
+
Ruby +
    +
  • buildPackLangVersion: Language Version
    • +
+
Docker +
    +
  • dockerFilePath: Path to the docker file
    • +
+
Ballerina +
    +
  • Not Applicable
    • +
      +
WSO2 MI +
    +
  • Not Applicable
    • +
      +
Manual TaskPython +
    +
  • buildPackLangVersion: Language Version
    • +
+
Node.JS +
    +
  • buildPackLangVersion: Language Version
    • +
+
Java +
    +
  • buildPackLangVersion: Language Version
    • +
+
Go +
    +
  • buildPackLangVersion: Language Version
    • +
+
.Net +
    +
  • buildPackLangVersion: Language Version
    • +
+
PHP +
    +
  • buildPackLangVersion: Language Version
    • +
+
Ruby +
    +
  • buildPackLangVersion: Language Version
    • +
+
Docker +
    +
  • dockerFilePath: Path to the docker file
    • +
+
Ballerina +
    +
  • Not Applicable
    • +
      +
WSO2 MI +
    +
  • Not Applicable
    • +
      +
+ + + diff --git a/en/pe-docs/docs/references/private-data-plane-management-models.md b/en/pe-docs/docs/references/private-data-plane-management-models.md new file mode 100644 index 000000000..8977083ad --- /dev/null +++ b/en/pe-docs/docs/references/private-data-plane-management-models.md @@ -0,0 +1,497 @@ +# Private Data Plane Management Models + +Choreo supports various management models for private data planes (PDPs), fostering collaboration between WSO2 and customers across diverse scenarios. The following sections provide insights into WSO2's fully managed solutions and shared responsibility models, allowing you to make informed decisions regarding cloud-based operations and security. + +## WSO2 fully managed (infrastructure and PDP in WSO2 subscription) model + +WSO2 fully managed private data planes are supported only on Azure, AWS, and GCP cloud providers. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
TaskTask descriptionResponsible partyAccountableConsultedInformed
Subscription prerequisites- Create subscriptions
+ - Check quota and service limits
+ - Run the Choreo compatibility prerequisite script		WSO2WSO2Customer (If required)Customer (If required)
Remote access for installationProvide owner accessWSO2WSO2WSO2WSO2
Network management- Obtain customers backend CIDR in case of VPN/peering
+ - Check end-to-end connectivity (primary and failover)		WSO2/CustomerWSO2/CustomerCustomerCustomer
Firewall rules/access controlSet up firewall and required rules depending on the security tierWSO2WSO2CustomerCustomer
Infrastructure provisioning- Provision Bastion
+ - Provision Kubernetes clusters		WSO2WSO2-Customer(If required)
Kubernetes cluster management- Manage Kubernetes versions
+ - Increase node pool size		WSO2WSO2CustomerCustomer
Infrastructure monitoringSet up alertsWSO2WSO2-Customer(If required)
DNS management for Choreo system- Manage DNS infrastructure
+ - Manage SSL certificates for Choreo system components		WSO2/CustomerWSO2/CustomerCustomerCustomer
Choreo system components deploymentSet up PDP agents via HelmWSO2WSO2--
Choreo system components managementUpgrade/patch/debug versionsWSO2WSO2-Customer(If required)
Choreo system components monitoring- Set up continuous monitoring 24x7
+ - Provide monthly uptime reports		WSO2WSO2-Customer
Choreo system security monitoringIf basic tier
+ - CSPM
+ - Apply security patches
+ - Manage supply chain security (Image scanning, SAST)
+ - Manage security incidents
+ If standard tier/premium tier
+ - CSPM
+ - Apply security patches
+ - Manage supply chain security
+ - Monitor runtime security alerts (Azure Defender)
+ - Monitor security incident and event management (SIEM) alerts
+ - Manage security incidents
+ - Adhere to compliance standards		WSO2/CustomerWSO2/CustomerWSO2/CustomerWSO2/Customer
Choreo application creation/deploymentCustomerCustomerCustomerCustomer
Choreo application managementCustomerCustomerCustomerCustomer
Choreo application monitoringCustomerCustomerCustomerCustomer
Choreo application logsCustomerCustomerCustomerCustomer
+ +## WSO2 fully managed (infrastructure and PDP in customer subscription) model + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
TaskTask descriptionResponsible partyAccountableConsultedInformed
Subscription prerequisites- Create subscriptions
+ - Check quota and service limits
+ - Run the Choreo compatibility prerequisite script		CustomerCustomerWSO2-
Remote access for installationProvide accessCustomerCustomerWSO2WSO2
Network management- Obtain customers backend CIDR in case of VPN/peering
+ - Check end-to-end connectivity (primary and failover)		WSO2/CustomerWSO2/CustomerCustomerCustomer
Firewall rules/access controlSet up firewall and required rules depending on the security tierWSO2/CustomerWSO2/CustomerCustomerCustomer
Infrastructure provisioning- Provision Bastion
+ - Provision Kubernetes clusters		WSO2WSO2CustomerCustomer
Kubernetes cluster management- Manage Kubernetes versions
+ - Increase node pool size		WSO2WSO2CustomerCustomer
Infrastructure monitoringSet up alertsWSO2WSO2-Customer(If required)
DNS management for Choreo system- Manage DNS infrastructure
+ - Manage SSL certificates for Choreo system components		WSO2/CustomerWSO2/CustomerCustomerCustomer
Choreo system components deploymentSet up PDP agents via HelmWSO2WSO2Customer-
Choreo system components managementUpgrade/patch/debug versionsWSO2WSO2-Customer(If required)
Choreo system components monitoring- Set up continuous monitoring 24x7
+ - Provide monthly uptime reports		WSO2WSO2-Customer
Choreo system security monitoringIf basic tier
+ - CSPM
+ - Apply security patches
+ - Manage supply chain security (Image scanning, SAST)
+ - Manage security incidents
+ If standard tier/premium tier
+ - CSPM
+ - Apply security patches
+ - Manage supply chain security
+ - Monitor runtime security alerts (Azure Defender)
+ - Monitor security incident and event management (SIEM) alerts
+ - Manage security incidents
+ - Adhere to compliance standards		WSO2/CustomerWSO2/CustomerWSO2/CustomerWSO2/Customer
Choreo application creation/deploymentCustomerCustomerCustomerCustomer
Choreo application managementCustomerCustomerCustomerCustomer
Choreo application monitoringCustomerCustomerCustomerCustomer
Choreo application logsCustomerCustomerCustomerCustomer
+ +## Customer self-managed (WSO2 provides installation script and updates) model + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
TaskTask descriptionResponsible partyAccountableConsultedInformed
Subscription prerequisites- Create subscriptions
+ - Check quota and service limits
+ - Run the Choreo compatibility prerequisite script		CustomerCustomerWSO2WSO2
Remote access for installationProvide owner accessCustomerCustomerWSO2-
Network management- Obtain customers backend CIDR in case of VPN/peering
+ - Check end-to-end connectivity (primary and failover)		CustomerCustomerWSO2WSO2
Firewall rules/access controlSet up firewall and required rules depending on the security tierCustomerCustomerWSO2WSO2
Infrastructure provisioning- Provision Bastion
+ - Provision Kubernetes clusters		CustomerCustomerWSO2WSO2(If required)
Kubernetes cluster management- Manage Kubernetes versions
+ - Increase node pool size		CustomerCustomerWSO2WSO2(If required)
Infrastructure monitoringSet up alertsCustomerCustomerWSO2-
DNS management for Choreo system- Manage DNS infrastructure
+ - Manage SSL certificates for Choreo system components		CustomerCustomerWSO2-
Choreo system components deploymentSet up PDP agents via HelmCustomerCustomerWSO2-
Choreo system components managementUpgrade/patch/debug versionsCustomerCustomerWSO2-
Choreo system components monitoring- Set up continuous monitoring 24x7
+ - Provide monthly uptime reports		CustomerCustomerWSO2-
Choreo system security monitoringIf basic tier
+ - CSPM
+ - Apply security patches
+ - Manage supply chain security (Image scanning, SAST)
+ - Manage security incidents
+ If standard tier/premium tier
+ - CSPM
+ - Apply security patches
+ - Manage supply chain security
+ - Monitor runtime security alerts (Azure Defender)
+ - Monitor security incident and event management (SIEM) alerts
+ - Manage security incidents
+ - Adhere to compliance standards		WSO2/CustomerWSO2/CustomerWSO2/CustomerWSO2/Customer
Choreo application creation/deploymentCustomerCustomerCustomerCustomer
Choreo application managementCustomerCustomerCustomerCustomer
Choreo application monitoringCustomerCustomerCustomerCustomer
Choreo application logsCustomerCustomerCustomerCustomer
diff --git a/en/pe-docs/docs/references/private-data-plane-security-levels.md b/en/pe-docs/docs/references/private-data-plane-security-levels.md new file mode 100644 index 000000000..b20104c6a --- /dev/null +++ b/en/pe-docs/docs/references/private-data-plane-security-levels.md @@ -0,0 +1,87 @@ +# Private Data Plane Security Levels + +The following table outlines the private data plane security levels supported in Choreo: + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Basic tierStandard tierPremium tier
Distributed denial-of-service (DDoS) protection basic *Distributed denial-of-service (DDoS) protection basic *Distributed denial-of-service (DDoS) protection premium *
Controlled admin access *Controlled admin access *Controlled admin access *
End-to-end data encryption in transitEnd-to-end data encryption in transitEnd-to-end data encryption in transit
Data encryption at rest *Data encryption at rest *Data encryption at rest *
Secret managementSecret managementSecret management
Foundational CSPM *Foundational CSPM *Premium CSPM *
Static application security testing (SAST)Static application security testing (SAST)Static application security testing (SAST)
Infrastructure as code (IaC) scanningInfrastructure as code (IaC) scanningInfrastructure as code (IaC) scanning
Software composition analysisSoftware composition analysisSoftware composition analysis
Docker image security scanningDocker image security scanningDocker image security scanning
N/AKubernetes runtime protection *Kubernetes runtime protection *
N/AWeb application firewall (WAF) *Web application firewall (WAF) *
N/AN/ANetwork firewall *
+ +\* Not available in the on-premises private data plane. + +!!! tip + Available add-ons:
+ - Security incident and event management (SIEM).
+ - 24/7 security operation center. diff --git a/en/pe-docs/docs/references/troubleshoot-choreo.md b/en/pe-docs/docs/references/troubleshoot-choreo.md new file mode 100644 index 000000000..ddb05ec51 --- /dev/null +++ b/en/pe-docs/docs/references/troubleshoot-choreo.md @@ -0,0 +1,109 @@ +# Troubleshoot Choreo + +This page walks you through common problems you may encounter when building and deploying components with Choreo, along with the recommended solutions to resolve each issue. + +## Troubleshoot component build errors + +- ### Deploying an Angular web application displays the Nginx welcome page instead of the application's homepage. + + This occurs due to specifying an incorrect build output directory when you set up your Angular application in Choreo. +To resolve the issue, follow the guidelines given below: + + - Ensure that the build output directory correctly points to where your Angular build script outputs the files. The deafult output directory is `dist/`. + - Make sure to reconfigure the build settings if the current configuration is incorrect. + +- ### An error occurs in the container Trivy scan when building a BYOC component. + + The recommended approach to address this issue is to fix the identified vulnerability and rebuild the component. + + However, if you want to add a `.trivyignore` file to overcome the issue, ensure to add it to the Docker build context path specified when creating the component. For example, `{buildContextPath}./trivyignore`. + +- ### The `config.js` file is not properly mounted in a web application. + + To resolve this issue, follow the steps given below: + + 1. Add the `config.js` file to the `app/public` directory in your repository. + 2. Reference it from the `index.html` file by adding a script tag as follows: + + `` + +## Troubleshoot component deployment errors + +- ### The `config.js` file is not properly integrated during the deployment of a React application, causing it to render with unexpected HTML instead of the expected JavaScript configuration. + + To ensure correct loading of the `config.js` file, follow the steps given below: + + - Reference the `config.js` file from the `index.html` file of your application by adding a script tag as follows: + + `` + + - Verify that the path in the script tag matches the location where the `config.js` file is stored in your repository. + - Make sure the script tag is placed within the `` tag in your `index.html` file. You must ensure that it is not mistakenly placed within another HTML element. + +- ### I'm not aware of the commits that can trigger an automatic build in Choreo. + + Merge commits and commits pushed directly to the branch can trigger a build in Choreo. + +## Troubleshoot web application issues + +- ### After building a web application, the Nginx welcome page is displayed instead of the web application home page. + + This can happen if an incorrect build output directory is specified during component creation. + + During the build process, output files including the `index.html` are copied to the Nginx root directory. To ensure that the correct files are copied during the build process, you must check the Docker build logs. + +- ### The language I prefer to use is not available as a buildpack. + + In such scenarios, you can use the Dockerfile buildpack to create the component. + +- ### I mistakenly used an incorrect build command when creating a web application. How can I update it before triggering a build? + + You can go to the build page of the component and update the build command in the build configurations section. + +## Troubleshoot managed-authentication issues + +- ### After securing a web application with managed authentication, I’m not able to add users who can sign in to the application. + + For step-by-step instructions on how to manage users with Choreo's built-in identity provider (IdP), see [Configure a User Store with the Built-In IdP](../api-management/consumer-idps/configure-a-user-store-with-built-in-idp.md). + + For details on setting up other OpenID Connect (OIDC) supported IdPs, see [Manage OAuth Keys](../authentication-and-authorization/secure-web-applications-with-managed-authentication/#step-3-manage-oauth-keys). + +## Troubleshoot Tailscale proxy issues + +- ### Where can I find logs to troubleshoot Tailscale proxy issues? + + To troubleshoot Tailscale proxy issues, you can view the [Runtime Logs](https://wso2.com/choreo/docs/monitoring-and-insights/view-logs/#runtime-logs) of the running container for your Tailscale proxy deployment. These logs can help you diagnose most of the issues. + You can also view real-time container logs via the **Runtime** page under **DevOps**. For more details, see [Observe real-time container logs](https://wso2.com/choreo/docs/devops-and-ci-cd/view-runtime-details/#observe-real-time-container-logs). + +- ### I'm not able to connect the Tailscale proxy node to my Tailscale network due to an authentication failure. + + - If you encounter the following log lines in your Tailscale proxy deployment, it indicates a misconfiguration of the `TS_AUTH_KEY`: + + ``` + 2024-06-04T10:38:53.885800940Z To authenticate, visit: + 2024-06-04T10:38:53.885802684Z + 2024-06-04T10:38:53.885815708Z https://login.tailscale.com/a/696841f011517 + 2024-06-04T10:38:53.885817457Z + 2024-06-04T10:38:55.194344862Z Waiting for tailscale up to complete... + 2024-06-04T10:38:57.198970796Z Waiting for tailscale up to complete... + 2024-06-04T10:38:59.203265659Z Waiting for tailscale up to complete... + ``` + To resolve this, you must re-check your authentication key and ensure you have entered the correct key. + + - If you encounter the following log lines in your Tailscale proxy deployment, it indicates that your authentication key is invalid or expired. + ``` + 2024-06-04T11:33:58.762363181Z 2024/06/04 11:33:58 Received error: invalid key: unable to validate API key + 2024-06-04T11:33:58.762458209Z backend error: invalid key: unable to validate API key + ``` + + To resolve this, you must verify the correctness of your authentication key. If the key has expired, you must generate a new key from Tailscale admin console. + + +- ### I'm not able to access private endpoints although the Tailscale proxy is properly connected to my Tailscale network. + + To resolve this, do the following: + + - Ensure your on-premises setup is properly connected to the Tailscale network and that specific services, database servers, etc., are running as expected in your on-premises setup. + - Verify that the IP addresses and ports specified in your `Config.yaml` file (mounted to Tailscale proxy during deployment) match the IP addresses in your Tailscale network. + - Cross-check the ports defined in the `endpoints.yaml` file with the port mappings in the `Config.yaml` file. + diff --git a/en/site/search-results.html b/en/pe-docs/docs/search-results.html similarity index 100% rename from en/site/search-results.html rename to en/pe-docs/docs/search-results.html diff --git a/en/pe-docs/docs/user-management/groups-and-roles/control-access-in-the-choreo-console.md b/en/pe-docs/docs/user-management/groups-and-roles/control-access-in-the-choreo-console.md new file mode 100644 index 000000000..087d7e05b --- /dev/null +++ b/en/pe-docs/docs/user-management/groups-and-roles/control-access-in-the-choreo-console.md @@ -0,0 +1,123 @@ +# Control Access in the Choreo Console + +In the Choreo Console, you have the ability to manage access to projects and the actions that can be performed within them. Administrators have the capability to restrict project access to specific user groups. This feature is useful when you need certain user groups to have access to particular projects or for a set of projects. + +Choreo uses **Roles**, **Groups**, and a **Mapping level** to control access to the Choreo Console as follows: + +- **Role** : Role is a collection of permissions. Choreo has a predefined set of roles with permissions assigned to them. [Learn more](../../choreo-concepts/organization.md#roles) +- **Group** : Group is a collection of users. A user group requires a role or multiple roles to be assigned to it so that the users in those groups get the relevant permissions via the assigned roles. [Learn more](../../choreo-concepts/organization.md#groups) + +- **Mapping level** : A mapping level defines the extent at which a role-group mapping can be done. Choreo has two defined resource levels. + - **Organization** : You can assign a role to a group or associate a group with a role within the organization. This ensures that + all users in a group inherit the permissions granted by that role across all organizational resources. + For example, if a user has edit_project permission at the organization mapping level, that user can edit all the projects in the organization. + - **Project** : You can assign a role to a group or associate a group with a role within a specific project resource. This ensures + that users in the group inherit the permissions granted by that role only within the context of the specified project. + For example, If a user has edit_project permission at the project mapping level, that user can only edit the specified project. + +In Choreo, authorization operates by assigning a role to a group at a specified level. The level at which the role is assigned determines the extent of permissions granted to users. + +!!! warning "Important" + Avoid assigning multiple roles to a single user across different projects or levels (organization and project). Such assignments can grant users unintended permission to some projects, allowing them to perform tasks they shouldn't have access to. Therefore, it is recommended to assign only one role to a user across projects or levels to ensure proper access control. + +!!! info + In Choreo, organization-level permissions take precedence over project-level permissions. + +To elaborate further, refer to the following diagram. + +The following diagram depicts a role-group assignment at a specific resource level. In the diagram, an admin user has assigned the Developer role to all members of the Engineering group within the Engineering Project. This grants users in the Engineering group the ability to perform all actions allowed by the Developer role within the Engineering Project. + +![Console access control](../../assets/img/administer/access-control-to-console.png) + +## Sample scenario + +Now that you understand the basic concepts of access control within the Choreo Console, let’s try out a sample scenario to manage access within a project. + +Assume you are overseeing the Engineering Project within your organization and you need to grant development access to specific users solely within this project. Here's a step-by-step guide on how to achieve this: + +### Step 1: Create a project + +Follow the steps given below to create a project: + +1. Go to [https://console.choreo.dev/](https://console.choreo.dev/) and sign in. This opens the organization home page. +2. On the organization home page, click **+ Create Project**. +3. Enter a display name, unique name, and description for the project. You can enter the values given below: + + !!! info + In the **Name** field, you must specify a name to uniquely identify your project in various contexts. The value is editable only at the time you create the project. You cannot change the name after you create the project. + + | **Field** | **Value** | + | ------------------------ | --------------------- | + | **Project Display Name** | `Engineering Project` | + | **Name** | `engineering-project` | + | **Project Description** | `My sample project` | + +4. Click **Create**. This creates the project and takes you to the project home page. + +### Step 2: Create a new group + +Follow the steps given below to create a group with the name `Engineering Project Developer`: + +1. In the Choreo Console, go to the top navigation menu, click the **Organization** list, and select the organization where you created your project. + +2. In the left navigation menu, click **User Management** and then click **Groups**. +3. Click **+ Create Group**. +4. Enter a group name and group description. You can enter the values given below: + + | **Field** | **Value** | + | --------------------- | -------------------------------------------------------------- | + | **Group Name** | `Engineering Project Developer` | + | **Group Description** | `Users with development access within the engineering project` | + +5. Click **Create**. + +### Step 3: Assign roles to the group + +Follow the steps given below to assign the **Developer** role to the **Engineering Project Developer** group that you created: + +1. In the Choreo Console, go to the top navigation menu, click the **Project** list, and select the **Engineering Project** that you created. +2. In the left navigation menu, click **User Management** and then click **Groups**. +3. On the **Groups** page, search for the **Engineering Project Developer** group and click the corresponding edit icon. +4. Click **Roles** tab and then click on **+Add Roles**. +5. In the **Add Roles to Group in Project** dialog that opens, click the **Roles** list and select **Developer**. +6. Click **Add**. This assigns the **Developer** role to the group. You should see the mapping level as **Project (Engineering Project)** indicating the scope of the mapping. + +This means that you have granted developer access to users in the Engineering Project Developer group in the scope of the Engineering Project. + +Now that you have set up access control, you can proceed to add users to the new group. + +### Step 4: Add users to the group + +There are two approaches you can follow to add users to the group. + +#### Add a new user as a project developer + +Follow the steps given below to add a new user as a project developer: + +1. In the Choreo Console, go to the top navigation menu, click the **Organization** list, and select the organization where you created your project. +2. In the left navigation menu, click **User Management**, then click **Users** . +3. Click **+Invite Users**. +4. In the **Invite Users** dialog, + 1. Specify the email addresses of the users in the **Emails** field. + 2. Click the **Groups** list and select **Engineering Project Developer**. +5. Click **Invite**. + +#### Add an existing user as a project developer + +Follow the steps given below to add an existing user as a project developer: + +1. In the Choreo Console, go to the top navigation menu, click the **Organization** list, and select the organization where you created your project. +2. In the left navigation menu, click **User Management**, then click **Users** . +3. Search for the existing user you want to add to the **Engineering Project Developer** group. +4. Click the edit icon corresponding to the user. +5. Click **+Assign Groups**. +6. In the **Add Groups to User** dialog, click the **Groups** list and select **Engineering Project Developer**. +7. Click **Add**. + +!!! tip + Make sure to remove the user from any other groups to avoid granting organization-level access unintentionally. + +!!! note + Existing groups are already mapped to similar roles at the organization level. Therefore, adding users to those groups or keeping users in them, will give organization-level access to the users. - When users are added to the **Engineering Project Developer** group, they will only have developer access to the **Engineering Project**. - You can invite new users or add existing users to new groups within the Engineering Project, and based on their requirements, assign roles like Developer, API Publisher, etc. + +Now you have successfully set up access control within your project. diff --git a/en/pe-docs/docs/user-management/users/configure-enterprise-login.md b/en/pe-docs/docs/user-management/users/configure-enterprise-login.md new file mode 100644 index 000000000..173b63562 --- /dev/null +++ b/en/pe-docs/docs/user-management/users/configure-enterprise-login.md @@ -0,0 +1,130 @@ +# Configure Enterprise Login + +With Choreo, you can configure enterprise login to allow users from an external identity provider (IdP) to sign in to Choreo seamlessly without changing their credentials. + +This guide walks you through the steps to configure enterprise login for your organization in Choreo. + +## Prerequisites + +Before you proceed with the configuration, set up the following: + +- A valid email domain for your organization. +- Access the Choreo Console at https://console.choreo.dev/ via your Google, GitHub, or Microsoft account. If you are a new user, create an organization with a unique organization name. For example, "Stark Industries". + +## Configure enterprise login for your Choreo organization + +To configure enterprise login for your Choreo organization, follow the steps given below: + +- **If you already have a support account with us**, send us your organization name/handle and the email domains specific to your organization through our support portal. + +- **If you do not have a support account with us yet**, send an email to `choreo-help@wso2.com` requesting to enable enterprise login for your organization. + +!!! tip + Ensure you include the following information in the request: + + - Organization name or handle. For example, “Stark Industries” or “starkindustries”. + - Email domains specific to your organization. For example, “@stark.com”, “@starkindustries.com”, and “@stark.eu. + +!!! note "Sample email" + Subject : [Stark Industries] Configure enterprise login + + Hi CS team, + + I need to configure enterprise login for my organization. Can you please do the necessary configurations to proceed? + + My organization details are as follows: + + - Organization name: Stark Industries + - Organization handle: starkindustries + - Email domains specific to my organization: “@stark.com”, “@starkindustries.com”, and “@stark.eu” + + Thank you. + +The Choreo support team will perform the necessary configurations and respond to you with a verification code. You must sign in to your domain host account and configure the DNS record for your email domain with the following values: + +| **Field** | **Value** | +| ---------------------------- | ---------------------------------------------- | +| **Name/Host/Alias** | Specify `@` or leave it blank | +| **Time to Live (TTL)** | Keep the default value or use `86400` | +| **Value/Answer/Destination** | wso2-domain-verification:<`verification_code`> | + +Now, you are ready to bring your own identity to Choreo. + +## Bring your own identity to Choreo + +When you create an organization in Choreo, an organization with the same name is provisioned for you in Asgardeo. To bring your own identity to Choreo, you must configure a federated enterprise IdP on Asgardeo in the organization that is provisioned for you. + +Follow the steps given below to configure the federated IdP: + +1. Sign in to [Asgardeo](https://asgardeo.io/). +2. To configure a federated enterprise identity provider for your Asgardeo organization, follow the steps in [Asgardeo documentation - Add Standard-Based Login](https://wso2.com/asgardeo/docs/guides/authentication/enterprise-login/). +3. In the Asgardeo Console left navigation menu, click **Applications**. You will see an application named **WSO2_LOGIN_FOR_CHOREO_CONSOLE**. +4. Click on the application to edit it. +5. Click the **Sign-in Method** tab. You can observe the configured connection. + +Now, users in your enterprise IdP can sign in to the Choreo Console using their enterprise IDs. + +## Configure role-based access control for enterprise login + +To streamline the enterprise login process and grant appropriate permission, Choreo provides the flexibility to configure role-based access control for users who reside in an external IdP. + +To set up role-based access control for enterprise login within Choreo, follow the steps given below: + +### Prerequisites + +Before you proceed with the configuration, make sure you complete the following: + +1. Configure enterprise login for your organization. For instructions, see [Configure enterprise login for your Choreo organization](#configure-enterprise-login-for-your-choreo-organization). +2. Ensure your enterprise identity provider includes the group/role attributes in tokens it sends to Asgardeo via the respective protocol. +3. Be sure you have administrator privileges in Choreo. + +### Step 1: Configure Asgardeo + +1. Sign in to [Asgardeo](https://asgardeo.io/). +2. [Configure your IdP as an external IdP in Asgardeo](https://wso2.com/asgardeo/docs/guides/authentication/enterprise-login/). Depending on your IdP, you can select OpenID Connect or SAML as the protocol between Asgardeo and your IdP. + + !!! note + If you are using OpenID Connect, configure the requested scopes accordingly for Asgardeo to get the relevant group/role details from the external IdP. + +3. To configure the application, follow the steps given below: + + 1. In the Asgardeo Console left navigation menu, click **Applications**. You will see an application named **WSO2_LOGIN_FOR_CHOREO_CONSOLE**. + 2. Click on the application to edit it. + 3. Click the **Sign-in Method** tab. + 4. Configure the IdP for login depending on the protocol you selected: + - For OpenID Connect, follow the instructions in [Enable the OIDC IdP for login](https://wso2.com/asgardeo/docs/guides/authentication/enterprise-login/add-oidc-idp-login/#enable-the-oidc-idp-for-login). + - For SAML, follow the instructions in [Enable the SAML IdP for login](https://wso2.com/asgardeo/docs/guides/authentication/enterprise-login/add-saml-idp-login/#enable-the-saml-idp-for-login). + 5. Click the **User Attributes** tab. + 6. Select the **Groups** attribute and click the arrow to expand the section. Then, select the **Requested** checkbox. + 7. Click **Update**. + +4. To add the user attributes as OpenID Connect scopes, follow the steps given below: + 1. In the Asgardeo Console left navigation menu, click **Scopes**. + 2. In the **OpenID Connect Scopes** pane, click **OpenID** to edit it. + 3. Click **New Attribute** and select the **Groups** attribute. + 4. Click **Save** and then click **Save Changes**. + +### Step 2: Map Choreo groups to enterprise IdP groups via the Choreo Console + +!!! note + + Before you map Choreo groups to enterprise IdP groups, ensure you meet the following criteria: + + - Asgardeo is your key manager. + - You have permission to perform actions of the organization administrator role. + +1. Sign in to the [Choreo Console](https://console.choreo.dev/). +2. In the Choreo Console, go to the top navigation menu and click **Organization**. This takes you to the organization's home page. +3. In the left navigation menu, click **User Management** and then click **Groups**. +4. Click **Manage IdP Group Mapping**. + ![Group mapping](../../assets/img/administer/enterprise-login/group-mapping.png) + +5. Click the edit icon corresponding to the Choreo group you want to map to the enterprise IdP group. +6. In the **IdP Group Name** field, specify the exact name you configured in the enterprise IdP and enter to add it. + +!!! tip + If there is a change to the IdP group mapping, it takes effect from the next login session onwards. + +7. Click **Save**. + +By following these steps, you have successfully configured role-based access control for enterprise login in Choreo, allowing users from the external IdP to have the appropriate permission. diff --git a/en/pe-docs/docs/user-management/users/inviting-members.md b/en/pe-docs/docs/user-management/users/inviting-members.md new file mode 100644 index 000000000..ef265e7cd --- /dev/null +++ b/en/pe-docs/docs/user-management/users/inviting-members.md @@ -0,0 +1,6 @@ +## Inviting users + +!!! note + - You must have **Send Invitations** or **Manage Invitations** permission under **USER-MANAGEMENT** permission group to invite users. + +Platform engineers can invite users to the organization by assigning them specific groups. Invited users will receive an invitation via email. An invited user must accept the invitation in order to join the organization and access the resources. diff --git a/en/pe-docs/docs/user-management/users/manage-members-of-an-organization.md b/en/pe-docs/docs/user-management/users/manage-members-of-an-organization.md new file mode 100644 index 000000000..e768fe954 --- /dev/null +++ b/en/pe-docs/docs/user-management/users/manage-members-of-an-organization.md @@ -0,0 +1,20 @@ +# Manage Members of an Organization + +An organization in Choreo is a logical grouping of users and user resources. A first-time user must create an organization and be a user of it when signing in to Choreo. Users and resources in an organization cannot access resources in another organization unless an admin of the other organization invites them and adds them as a user of that organization. + +{% include "inviting-members.md" %} + +Follow the steps below to invite a new member to your organization: + +1. Sign in to the [Choreo Console](https://console.choreo.dev/). +2. In the top navigation menu, click the **Organization** list and select your organization. +3. In the left navigation menu, click **User Management** and then click **Users**. +4. Click on **+ Invite Users** +5. In the **Invite Users** dialog, + 1. Specify the email addresses of the users in the **Emails** field. + 2. Click the **Groups** list and select at least one group. +6. Click **Invite**. + +## Manage user permission + +For details on how Choreo manages user permission, see [Manage user permission](../../choreo-concepts/organization.md#manage-user-permission). diff --git a/en/pe-docs/docs/what-is-choreo.md b/en/pe-docs/docs/what-is-choreo.md new file mode 100644 index 000000000..a2b88445f --- /dev/null +++ b/en/pe-docs/docs/what-is-choreo.md @@ -0,0 +1,39 @@ +# What is Choreo? + +Choreo is an internal developer platform designed to redefine how you create digital experiences. It empowers you to seamlessly design, develop, deploy, and govern cloud-native applications, unlocking innovation while reducing time-to-market. Just add developers to Choreo while maintaining operational control. + +## Key capabilities of Choreo + +### Design for security, governance, and efficiency +- **Domain-Driven Design**: Organize enterprise systems into domains, exposing managed APIs, events, and data through projects. Each project consists of components representing units of deployment. +- **Application Security Design**: Leverage [cell-based architecture](https://github.com/wso2/reference-architecture/blob/master/reference-architecture-cell-based.md), where projects become governable units from development to deployment, ensuring managed access via APIs, events, and data. + +### Efficient and effective development +- **Code in Any Language**: Develop applications in your team's preferred programming language, harnessing existing skill sets to build powerful polyglot APIs, services, events, tasks, and more. +- **Native Support for VS Code**: Seamlessly collaborate and manage code using VS Code in a feature-rich, visually-enhanced development environment. +- **Git Repository Integration**: Effortlessly connect to Git-based platforms like GitHub, Bitbucket, or GitLab to develop components by linking an existing repository. + +### Seamless deployment +- **CI/CD**: Eliminate manual builds and unreliable deployments with Choreo's industry-standard CI/CD tooling, providing complete control and flexibility. +- **Multi-Cloud Kubernetes**: Easily deliver cloud-native applications across Azure, AWS, GCP, or your Kubernetes clusters. +- **Configuration Management**: Centralize configuration parameters, sensitive credentials, and secrets across deployment environments via an intuitive interface. + +### Effortless management of APIs, integrations, microservices, and web applications +- **Enable Security**: Empower security teams to manage data flows, ensuring seamless control over sensitive information like access credentials. +- **Scale Up or Down**: Kubernetes handles scaling automatically, optimizing costs by scaling services based on demand. +- **Ensure Reliability**: DevOps and SRE teams can easily manage deployed components with built-in insights and observability. + +### Reusable digital assets +- **Control Visibility and Sharing**: Publish your digital assets to a shared marketplace for consumption by internal or external stakeholders, managed by role-based access control. +- **Internal Marketplace**: Choreo's secure internal marketplace fosters transparency and efficiency with granular access control for publishers and consumers. + +### Comprehensive observability +- **Anomaly Detection**: Stay ahead of issues with prompt notifications, ensuring balanced scaling and immediate action during unexpected mishaps. +- **Troubleshoot and Debug**: Quickly pinpoint and address root causes using detailed logs and data aligned in the same timeline, down to the machine-level details. + +### Robust governance +- **DORA Metrics**: Monitor your DevOps efficiency with Choreo DORA metrics, experiencing rapid improvements in time from deployment to production safely and robustly. +- **Engineering Insights**: Gain visibility into engineering insights and advanced data analytics to make data-driven decisions, optimize processes, and improve efficiency. +- **API Analytics**: Understand API performance and adoption patterns to identify and resolve operational bottlenecks. + +Choreo is your all-in-one platform for building, deploying, and managing cloud-native applications with ease, security, and efficiency. diff --git a/en/pe-docs/mkdocs.yml b/en/pe-docs/mkdocs.yml new file mode 100644 index 000000000..568664d64 --- /dev/null +++ b/en/pe-docs/mkdocs.yml @@ -0,0 +1,253 @@ +# Copyright (c) 2021, WSO2 Inc. (http://www.wso2.org) All Rights Reserved. +# +# WSO2 Inc. licenses this file to you under the Apache License, +# Version 2.0 (the "License"); you may not use this file except +# in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, +# software distributed under the License is distributed on an +# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +# KIND, either express or implied. See the License for the +# specific language governing permissions and limitations +# under the License. + +# Project information +site_name: "" +site_description: Choreo Learning Portal +site_author: WSO2 +site_url: https://wso2.com/choreo/docs +site_dir: site/platform-engineer + +# Repository +repo_name: wso2/docs-choreo-dev +repo_url: https://github.com/wso2/docs-choreo-dev/ +edit_uri: https://github.com/wso2/docs-choreo-dev/edit/dev/en/docs/ +dev_addr: localhost:8000 + +# Copyright +copyright: ©2023 WSO2 LLC. + +# Configuration +theme: + name: material + custom_dir: ../theme/material + logo: assets/images/logo.png + font: + text: Montserrat + favicon: assets/images/favicon.png + features: + - navigation.expand + - navigation.path + - navigation.top + - content.code.copy + - content.action.edit + - content.action.view + - version.selector + language: "en" + palette: + # Palette toggle for automatic mode + - media: "(prefers-color-scheme)" + toggle: + icon: material/brightness-auto + name: Switch to dark mode + + # Palette toggle for light mode + - media: "(prefers-color-scheme: light)" + scheme: default + toggle: + icon: material/brightness-7 + name: Switch to system preference + + # Palette toggle for dark mode + - media: "(prefers-color-scheme: dark)" + scheme: slate + toggle: + icon: material/brightness-4 + name: Switch to light mode + icon: + logo: logo +#Breaks build if there's a warning +strict: false +# Navigation +nav: + - Home: index.md + - Introduction: + - What is Choreo?: what-is-choreo.md + - Choreo Concepts: + - Resource Hierarchy: choreo-concepts/resource-hierarchy.md + - Organization: choreo-concepts/organization.md + - Data Planes: choreo-concepts/data-planes.md + - Environments: choreo-concepts/environments.md + - CI/CD: choreo-concepts/ci-cd.md + - Choreo Marketplace: choreo-concepts/choreo-marketplace.md + - Project: choreo-concepts/project.md + - Component: choreo-concepts/component.md + - Deployment Tracks: choreo-concepts/deployment-tracks.md + - Endpoint: choreo-concepts/endpoint.md + - Connections: choreo-concepts/connections.md + - Infrastructure: + - Data Planes: 'infrastructure/dataplanes/data-planes.md' + - Environments: + - Manage Environments: infrastructure/environments/manage-environments.md + - Domains: + - Configure a Custom Domain for Your Organization: infrastructure/domains/configure-a-custom-domain-for-your-organization.md + - Configure VPNs on Cloud Data Plane: 'infrastructure/configure-vpns-on-the-choreo-cloud-data-plane.md' + - Credentials: + - Set Up Git Provider Authentication: infrastructure/credentials/set-up-git-provider-authentication-for-choreo-deployments.md + - Use Your Own Container Registry: infrastructure/credentials/use-your-own-container-registry.md + - User Management: + - Users: + - Manage Members of an Organization: user-management/users/manage-members-of-an-organization.md + - Configure Enterprise Login: user-management/users/configure-enterprise-login.md + - Groups & Roles: + - Control Access in the Choreo Console: user-management/groups-and-roles/control-access-in-the-choreo-console.md + - DevOps: + - CI Pipelines: + - Configure CI Pipeline: devops/ci-pipelines/configure-ci-pipeline.md + - Integrate Unit Tests into the CI Pipeline: devops/ci-pipelines/integrate-unit-tests-into-the-build-pipeline.md + - CI Pipeline logs: 'devops/ci-pipelines/ci-pipeline-logs.md' + - CD Pipelines: + - Deploy Applications using Choreo CD Pipeline: devops/cd-pipelines/deploying-application-using-choreo-cd-pipeline.md + - Manage CD Pipelines: 'devops/cd-pipelines/manage-continuous-deployment-pipelines.md' + - Manage Configuration Groups: devops/manage-configuration-groups.md + - Governance: + - Workflows: + - Configure Approvals for Choreo Workflows: governance/workflows/configure-approvals-for-choreo-workflows.md + - Egress Control: + - Control Egress Traffic for Your Choreo Organization: governance/egress-control/control-egress-traffic-for-your-organization.md + - Approvals: + - Review Workflow Approval Requests: governance/approvals/review-workflow-approval-requests.md + - DB & Services: + - Database & Vector Databases: + - Overview: db-and-services/databases/choreo-managed-databases-and-caches.md + - PostgreSQL: db-and-services/databases/choreo-managed-postgresql-databases.md + - MySQL: db-and-services/databases/choreo-managed-mysql-databases.md + - Choreo-Managed Cache: db-and-services/databases/choreo-managed-caches.md + - Add Choreo-Managed Databases and Caches to the Marketplace: db-and-services/databases/add-choreo-managed-databases-and-caches-to-the-marketplace.md + - Third-Party Services: db-and-services/external-services/integrate-and-manage-third-party-services.md + - Message Brokers: + - Overview: db-and-services/message-brokers/choreo-managed-message-brokers.md + - Create Choreo-Managed Kafka Services: db-and-services/message-brokers/create-choreo-managed-kafka-services.md + - Configure a Kafka Service: db-and-services/message-brokers/configure-a-kafka-service.md + - Monitor a Kafka Service: db-and-services/message-brokers/monitor-a-kafka-service.md + - Gen AI Services: db-and-services/external-services/integrate-and-manage-gen-ai-services.md + - K8s Operations: + - Runtime: + - View Kubernetes Runtime Details: k8s-operations/runtime/view-runtime-details.md + - Containers: + - Configure Kubernetes Container Resources, Commands, and Arguments: k8s-operations/containers/configure-container-resources-commands-and-arguments.md + - K8s Configurations and Secrets: k8s-operations/manage-configurations-and-secrets.md + - Health Checks: k8s-operations/set-up-health-checks.md + - Scaling: + - Autoscale Component Replicas: k8s-operations/scaling/autoscale-component-replicas.md + - Autoscale Components with Scale-to-Zero: k8s-operations/scaling/autoscale-components-with-scale-to-zero.md + - Storage: k8s-operations/storage/configure-storage.md + - Insights: + - Delivery Insights: + - Configure Delivery Insights: insights/delivery-insights/configure-delivery-insights.md + - View Delivery Insights: insights/delivery-insights/view-delivery-insights.md + - Integrate External Insights Platforms: + - Work with the Choreo Insights API: + - Access the Choreo Insights API: insights/work-with-choreo-insights-api/access-the-choreo-insights-api.md + - Choreo Insights API: insights/work-with-choreo-insights-api/choreo-insights-api.md + - Cost Insights: insights/cost-optimization.md + - Observability: + - Alerts: + - Configure Alerts: observability/alerts/configure-alerts.md + - Runtime Logs: observability/runtime-logs.md + - Private Data Plane Logs: observability/private-data-plane-logs.md + - Audit Logs: observability/audit-logs.md + - API Management: + - Developer Portal: + - Customize the Choreo Developer Portal: api-management/developer-portal/customize-the-developer-portal.md + - API Analytics: + - Integrate Choreo with Moesif for Analytics: api-management/api-analytics/integrate-choreo-with-moesif.md + - Consumer IDPs: + - Set Up a User Store with Choreo’s Built-In Identity Provider: api-management/consumer-idps/configure-a-user-store-with-built-in-idp.md + - Set Up Asgardeo as an External IdP for Choreo APIs: api-management/consumer-idps/configure-asgardeo-as-an-external-idp.md + - Set Up Azure AD as an External IdP for Choreo APIs: api-management/consumer-idps/configure-azure-ad-as-an-external-idp.md + - Choreo CLI: + - Choreo CLI Overview: choreo-cli/choreo-cli-overview.md + - Get Started with the Choreo CLI: choreo-cli/get-started-with-the-choreo-cli.md + - Manage Authentication with Personal Access Tokens in Choreo CLI: choreo-cli/manage-authentication-with-personal-access-tokens.md + - References: + - FAQ: references/faq.md + - Choreo Limitations: references/choreo-limitations.md + - Troubleshoot Choreo: references/troubleshoot-choreo.md + - Private Data Plane Security Levels: references/private-data-plane-security-levels.md + - Private Data Plane Management Models: references/private-data-plane-management-models.md + - Choreo Platform Service Billing and Upgrades: references/choreo-platform-services-billing-and-upgrades.md + +# Extensions +# Extensions +markdown_extensions: + - markdown.extensions.admonition + - markdown.extensions.def_list + - markdown.extensions.footnotes + - markdown.extensions.toc: + permalink: true + toc_depth: 3 + - pymdownx.arithmatex + - pymdownx.betterem: + smart_enable: all + - pymdownx.caret + - pymdownx.critic + - pymdownx.details + - pymdownx.emoji: + emoji_generator: !!python/name:pymdownx.emoji.to_svg + - pymdownx.highlight: + anchor_linenums: true + pygments_lang_class: true + - pymdownx.keys + - pymdownx.mark + - pymdownx.smartsymbols + - pymdownx.superfences + - pymdownx.tabbed: + alternate_style: true + - pymdownx.tasklist: + custom_checkbox: true + - pymdownx.tilde + - pymdownx.snippets: + base_path: docs + - attr_list +plugins: + - search + - include-markdown + - glightbox + - open-in-new-tab + - markdownextradata: {} +extra_css: + # - assets/lib/highlightjs/default.min.css + # - assets/css/theme.css + # - assets/css/prism.css + # - assets/lib/json-formatter/json-formatter.css + + - assets/lib/highlightjs/styles/vs.min.css + - assets/css/blue-palette-alt2.css + - assets/css/choreotheme.css + - assets/lib/json-formatter/json-formatter.css + - assets/css/config-catalog.css + - assets/lib/fontawesome-free-6.3.0-web/css/all.min.css +extra_javascript: + - assets/lib/json-formatter/json-formatter.umd.js + - assets/lib/highlightjs/highlight.min.js + # - assets/js/theme.js + #- assets/js/prism-ballerina.js + - assets/js/choreotheme.js + +extra: + social: + - icon: fontawesome/brands/github + link: https://github.com/wso2 + version: + provider: mike + # Perspective dropdown configurations + show_perspective_dropdown: true + developer_docs_path: /choreo/docs/developer/ + pe_docs_path: /choreo/docs/platform-engineer/ +#site_version: 1.0.0 +#base_path: http://localhost:8000 + diff --git a/en/requirements.txt b/en/requirements.txt index d1346540f..2ef15e98d 100644 --- a/en/requirements.txt +++ b/en/requirements.txt @@ -13,4 +13,4 @@ markdown-include==0.8.1 jinja2==3.1.2 mkdocs-glightbox==0.3.4 mkdocs-include-markdown-plugin==1.0.0 -mkdocs-open-in-new-tab==1.0.3 \ No newline at end of file +mkdocs-open-in-new-tab==1.0.3 diff --git a/en/serve.sh b/en/serve.sh index c42f48d8c..82b8e6671 100755 --- a/en/serve.sh +++ b/en/serve.sh @@ -3,8 +3,10 @@ mdspell -V mdspell -n -a --en-us docs/**/*.md -d dictionary/en_US-large mdspell -n -a --en-us docs/**/**/*.md -d dictionary/en_US-large -mdspell -n -a --en-us mkdocs.yml -d dictionary/en_US-large +mdspell -n -a --en-us developer-docs/mkdocs.yml -d dictionary/en_US-large +mdspell -n -a --en-us pe-docs/mkdocs.yml -d dictionary/en_US-large mdspell -n -a --en-us theme/material/templates/home-page2.html -d dictionary/en_US-large +mdspell -n -a --en-us theme/material/templates/pe-home-page.html -d dictionary/en_US-large find docs/** -type f -name '*.md' | xargs -L1 markdown-link-check -c ./markdown-link-check-config.json --quiet || exit 1 find docs/**/* -type f -name '*.md' | xargs -L1 markdown-link-check -c ./markdown-link-check-config.json --quiet || exit 1 mkdocs build -c diff --git a/en/site/404.html b/en/site/404.html deleted file mode 100644 index e4f7426ed..000000000 --- a/en/site/404.html +++ /dev/null @@ -1,2985 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
-
- -
- - - - - - -
- - -
- -
- - - - - - - -
-
- - - -
-
-
- - - - -
-
-
- - - -
-
-
- - - -
-
-
- - - -
-
- -

404 - Not found. Try one of the menu links or use the search engine in the top right corner.

- -
-
- - -
- - - -
- - -
- -
-
-
-
- Copyright © WSO2 LLC (2023-2024) -
-
- Content licensed under CC By 4.0. | Sample code - licensed under Apache 2.0. -
-
-
-
-
- - - -
-
-
- - - - - - - - - - - - - - - - - \ No newline at end of file diff --git a/en/site/administer/configure-a-custom-domain-for-apis/index.html b/en/site/administer/configure-a-custom-domain-for-apis/index.html deleted file mode 100644 index 653fc71a6..000000000 --- a/en/site/administer/configure-a-custom-domain-for-apis/index.html +++ /dev/null @@ -1,15 +0,0 @@ - - - - - - Redirecting... - - - - - - -Redirecting... - - diff --git a/en/site/administer/configure-a-custom-domain-for-your-organization/index.html b/en/site/administer/configure-a-custom-domain-for-your-organization/index.html deleted file mode 100644 index 865743920..000000000 --- a/en/site/administer/configure-a-custom-domain-for-your-organization/index.html +++ /dev/null @@ -1,3407 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - Configure a Custom Domain for Your Organization - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- - - -
- - - - - - -
- - -
- -
- - - - - - - -
-
- - - -
-
-
- - - - -
-
-
- - - -
-
-
- - - -
-
-
- - - -
-
- - - - - - - - - - - - - - - - - - - - -

Configure a Custom Domain for Your Organization

-

A custom domain is essential for effective branding, discoverability, and credibility of a website. Choreo allows you to easily configure custom domains for your organization, enabling developers to utilize it to configure custom URLs for their components such as API proxies, services, web applications, and webhooks.

-

This section provides an overview of Choreo’s custom domain configuration model and guides you through configuring a custom domain for your organization. It also walks you through utilizing a custom domain to configure a custom URL for a component.

-

Choreo custom domain configuration model

-

Choreo allows organization administrators to add custom domains for their organizations. When an administrator adds custom domains to an organization, component developers can submit requests to utilize the custom domains for their respective components. These requests require approval from the organization administrator. Upon approval, the custom domain and the relevant URL customization become available to the component.

-

Configure a custom domain for an organization

-

Prerequisites

-
    -
  1. Sign in to the Choreo Console.
    2. -
  2. -

    Create an organization in Choreo.

    -

    Create an organization in Choreo

    -
    3. -
-

Add a custom domain

-

To add a custom domain for your organization, follow the steps given below:

-
-

Note

-

To add a custom domain, you must have organization administrator privileges.

-
-
    -
  1. Sign in to the Choreo Console.
    2. -
  2. In the Choreo Console header, click the Organization list.
    3. -
  3. In the left navigation menu, click Settings. This opens the organization-level settings page.
    4. -
  4. Click the URL Settings tab and then click the Active Domains tab.
    5. -
  5. Click + Add Domains.
    6. -
  6. -

    In the Add a Custom Domain pane, do the following:

    -
      -
    1. Enter your domain name.
      2. -
    2. Select the environment to apply the domain name.
      3. -
    3. -

      Select the entity type to apply the domain name.

      -
      -

      Tip

      -

      In this context:

      -
        -
      • The API entity type represents Choreo components exposed via an endpoint, including API Proxy, Service, and Webhook components.
        • -
      • The Web App entity type represents the Web Application component.
        • -
      -
      -
      4. -
    -
    7. -
  7. -

    Take a look at the generated CNAME target value displayed and create a DNS record associating the domain name to the CNAME target value with your DNS provider.

    -

    CNAME target value

    -
    -

    Info

    -

    When you select Developer Portal as the type, the environment is not applicable, and the CNAME alias will be displayed as follows: - Developer Portal CNAME target value

    -
    -
    8. -
  8. -

    Once the CNAME type DNS record is created, click Verify.

    -
    -

    Note

    -

    If the CNAME mapping is correct, the verification completes successfully. It can take some time for the configured CNAME mapping to be globally available.

    -
    -
    9. -
  9. -

    On successful verification of the custom domain, click Next.

    -
    10. -
  10. -

    Select a TLS certificate provider depending on your preference. You can either import the TLS certificates you created for the custom domain or click Let's Encrypt to allow Choreo to generate and manage the certificates for you.

    -
    -

    If you want to import your own certificate, it should adhere to specific guidelines

    -
      -
    • TLS certificate guidelines:
        -
      • It should be issued by a certificate authority (CA) and should contain the domain's public key along with additional information such as the domain name, the company that owns the domain, the certificate's expiration date, and the digital signature of the issuing CA.
        • -
      • It should be an X509 certificate.
        • -
      • It should be in the PEM format.
        • -
      • It should be issued directly or through a wildcard entry for the provided custom URL. For example,
          -
        • For direct issuance, the SSL file must include the exact domain name. For example, if the domain is apis.choreo.dev, the SSL file must include apis.choreo.com.
          • -
        • For wildcard entries, the SSL file should use a wildcard notation to cover all subdomains under the provided URL. For example, if the CNAME is apis.choreo.dev, the SSL file should use *.choreo.dev.
          • -
        -
        • -
      -
      • -
    • TLS key file guidelines:
        -
      • It should be in the PEM format.
        • -
      • It must be encrypted using RSA encryption.
        • -
      -
      • -
    • Certificate chain file guidelines:
        -
      • The chain file, which is essential for some clients to verify the authenticity of a server's SSL/TLS certificate, should contain your domain's SSL/TLS certificate (optional, as this can be provided via the certificate itself) and one or more intermediate certificates in the correct order, leading back to a root certificate.
        • -
      • All certificates in the chain should be X509 certificates in PEM format.
        • -
      -
      • -
    -
    -

    To proceed with this step in this guide, click Let's Encrypt.

    -
    11. -
  11. -

    To save the custom domain, click Add.

    -
    12. -
-

Now, you have successfully added a custom domain for your organization.

-

You can see the added custom domain listed in the Active Domains tab under the URL Settings tab.

-

Active domains

-

The custom domain you added will be available to the entity types in the specified environment. You can request the custom domain when configuring a custom URL for a component.

-
-

Note

-

If you add a custom domain for the Developer Portal type, the customization is applied immediately, and you can access the organization’s Developer Portal via the added domain.

-
-

If you want to view the entity types that use a particular custom domain, click the specific custom domain listed in the Active Domains tab under URL Settings.

-

Configure a custom URL for a component

-

When an organization administrator adds custom domains for specific environments, developers can request any available custom domain to configure a custom URL for a component in a specific environment.

-

Request a custom URL for a component

-

To request a custom URL for your component, follow the steps given below:

-
-

Note

-

Before you request a custom domain for a specific environment, ensure that the component is deployed to that environment.

-
-
    -
  1. Sign in to the Choreo Console.
    2. -
  2. In the Component Listing pane, click on the component for which you want to customize the URL.
    3. -
  3. In the left navigation menu, click Settings. This opens the component-level settings page.
    4. -
  4. -

    Click the URL Settings tab. This displays the active deployments of the component across different environments and indicates whether a custom URL is configured. If an active custom domain is available to configure a custom URL for a component in a specific environment, the Edit URL Mapping icon in the corresponding Action column becomes enabled.

    -

    Active deployments

    -
    5. -
  5. -

    To configure a custom URL for a component in a specific environment, click the Edit URL Mapping icon under the Action column corresponding to the respective environment. This opens the URL Settings dialog, where you can specify values to request for a custom URL.

    -

    URL settings

    -
    6. -
  6. -

    In the URL Settings dialog, select a domain to configure a custom URL.

    -
    -

    Tip

    -
      -
    • The Domain drop-down lists the available domains for the component. You can request for any listed domain.
      • -
    • If you want to request a custom URL for an API, you must specify an appropriate context path in the Path field. The Path field displays the default context path for the API. You can edit the path depending on your preference.
      • -
    -
    -
    7. -
  7. -

    Click Configure. This creates the custom URL mapping, which you can see under the URL Settings tab. The custom URL request will be in the Pending status until an organization administrator approves the request.

    -

    Pending custom URL request

    -
    8. -
-

Approve a custom URL request

-

When a developer requests a custom URL, the request will be listed in the organization-level settings page under the URL Settings tab.

-

To approve a custom URL mapping, follow the steps given below:

-
-

Note

-

To approve custom URL requests, you must have organization administrator privileges.

-
-
    -
  1. Sign in to the Choreo Console.
    2. -
  2. In the Choreo Console header, click the Organization list.
    3. -
  3. In the left navigation menu, click Settings. This opens the organization-level settings page.
    4. -
  4. -

    Click the URL Settings tab and then click the Pending URL Requests tab. You will see all the pending URL mapping requests sent by developers.

    -

    Pending URL requests

    -
    5. -
  5. -

    Go to the custom URL you want to approve and click the corresponding Approve URL Mapping icon under the Action column.

    -
    6. -
  6. Review the details and click Approve.
    7. -
-

Once approved, the invoke URL of the component gets replaced with the configured custom URL.

-

Custom URL

-

Now you have successfully utilized the configured custom domain to set up a custom URL for a component.

- - - - - - -
-
- - -
- - - -
- - -
- - - -
-
-
- - - - - - - - - - - - - - - - - \ No newline at end of file diff --git a/en/site/administer/configure-a-user-store-with-built-in-idp/index.html b/en/site/administer/configure-a-user-store-with-built-in-idp/index.html deleted file mode 100644 index 334b69099..000000000 --- a/en/site/administer/configure-a-user-store-with-built-in-idp/index.html +++ /dev/null @@ -1,3180 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - Configure a User Store with the Built-In Identity Provider - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- - - -
- - - - - - -
- - -
- -
- - - - - - - -
-
- - - -
-
-
- - - - -
-
-
- - - -
-
-
- - - -
-
-
- - - -
-
- - - - - - - - - - - - - - - - - - - - -

Configure a User Store with the Built-In Identity Provider

-

Developers looking to experiment with a complete application development process that includes user authentication and authorization can utilize Choreo's built-in identity provider (IdP). Choreo's built-in identity provider allows you to seamlessly test your application's authentication by setting up test users and groups within Choreo.

-
-

Note

-

Although the built-in IdP facilitates user management support, it is limited to adding users with attributes and groups. Therefore, the built-in IdP user management capabilities are not recommended for use in production.

-
-

Prerequisites

-

Before you try out the steps in this guide, be sure you have administrator rights to your Choreo organization. This permission is essential to configure a user store with the built-in IdP.

-

Configure a Choreo built-in IdP user store

-

Follow the steps given below to configure a Choreo built-in IdP user store for an environment:

-
    -
  1. Go to https://console.choreo.dev/ and sign in.
    2. -
  2. In the Choreo Console top navigation menu, click the Organization list and then click on your organization.
    3. -
  3. In the left navigation menu, click Settings. This takes you to your organization settings.
    4. -
  4. Click the Application Security tab and then click the Identity Providers tab.
    5. -
  5. On the Identity Providers tab, click Manage in the Choreo Built-in Identity Provider pane.
    6. -
  6. In the Manage IdP pane, click on a specific environment tab depending on where you want to configure the built-in IdP user store.
    7. -
  7. You can download the sample User store template file(.csv ) from the User Store section. The template file content is similar to the following:
    8. -
-
username,password,groups,first_name,last_name,email
-"demouser","password1","[manager, engineering]","John","Doe","john@acme.org"
-
- -
-

Note

-

The provided template file includes a sample user with associated attributes. To add new users, insert additional rows in the .csv file. To include more user attributes, add columns as required in the .csv file.

-
-
    -
  1. Specify appropriate user details in the template file and save it.
    2. -
  2. Select the template file that you saved and click Upload. A successful upload creates the user store and displays the configured users in the Users section.
    3. -
- - - - - - -
-
- - -
- - - -
- - -
- - - -
-
-
- - - - - - - - - - - - - - - - - \ No newline at end of file diff --git a/en/site/administer/configure-an-external-idp/configure-asgardeo-as-an-external-idp/index.html b/en/site/administer/configure-an-external-idp/configure-asgardeo-as-an-external-idp/index.html deleted file mode 100644 index f5f201ee1..000000000 --- a/en/site/administer/configure-an-external-idp/configure-asgardeo-as-an-external-idp/index.html +++ /dev/null @@ -1,3190 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - Configure Asgardeo as an External IdP - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- - - -
- - - - - - -
- - -
- -
- - - - - - - -
-
- - - -
-
-
- - - - -
-
-
- - - -
-
-
- - - -
-
-
- - - -
-
- - - - - - - - - - - - - - - - - - - - -

Configure Asgardeo as an External Identity Provider (IdP)

-

Asgardeo is an identity-as-a-service (IDaaS) solution designed to create seamless login experiences for your applications. Asgardeo seamlessly integrates with Choreo, providing powerful API access control through the use of API scopes. This enables restricting API access to designated user groups. By configuring Asgardeo as an external IdP in Choreo, you can leverage your Asgardeo user stores to manage API access control effectively. This guide walks you through the steps to set up Asgardeo as your external IdP.

-

Prerequisites

-

Before you proceed, be sure to complete the following:

-
    -
  • -

    Create an Asgardeo application. You can follow the Asgardeo guide to register a standard-based application.

    -
    • -
  • -

    Find the well-known URL: - Go to the info tab of the Asgardeo application to view the endpoints and copy the Discovery endpoint.

    -
    • -
  • -

    Find the Client ID: - Go to the Protocol tab of the Asgardeo application and copy the Client ID.

    -
    • -
-

Add Asgardeo as an external IdP in Choreo

-

Follow the steps below to add Asgardeo as an external IdP in Choreo:

-
    -
  1. Sign in to the Choreo Console at https://console.choreo.dev/.
    2. -
  2. In the left navigation menu, click Settings.
    3. -
  3. In the header, click the Organization list. This opens the organization-level settings page.
    4. -
  4. Click the Application Security tab and then click the Identity Providers tab.
    5. -
  5. To add an identity provider, click + Identity Provider.
    6. -
  6. Click Asgardeo.
    7. -
  7. In the Asgardeo dialog that opens, specify a name and a description for the IdP.
    8. -
  8. In the Well-Known URL field, paste the well-known URL that you copied from your Asgardeo instance by following the prerequisites.
    9. -
  9. -

    Leave the Apply to all environments checkbox selected. This allows you to use the tokens generated via this IdP to invoke APIs across all environments.

    -
    -

    Note

    -

    If you want to restrict the use of tokens generated via this IdP to invoke APIs in specific environments, clear the Apply to all environments checkbox and select the necessary environments from the Environments list.

    -
    -
    10. -
  10. -

    Click Next. This displays the server endpoints that are useful to implement and configure authentication for your application.

    -
    11. -
  11. Click Add.
    12. -
-

Now you have configured Asgardeo as an external IdP in Choreo.

- - - - - - -
-
- - -
- - - -
- - -
- - - -
-
-
- - - - - - - - - - - - - - - - - \ No newline at end of file diff --git a/en/site/administer/configure-an-external-idp/configure-azure-ad-as-an-external-idp/index.html b/en/site/administer/configure-an-external-idp/configure-azure-ad-as-an-external-idp/index.html deleted file mode 100644 index 01c52a1e4..000000000 --- a/en/site/administer/configure-an-external-idp/configure-azure-ad-as-an-external-idp/index.html +++ /dev/null @@ -1,3182 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - Configure Azure as an External IdP - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- - - -
- - - - - - -
- - -
- -
- - - - - - - -
-
- - - -
-
-
- - - - -
-
-
- - - -
-
-
- - - -
-
-
- - - -
-
- - - - - - - - - - - - - - - - - - - - -

Configure Azure Active Directory (Azure AD) as an External Identity Provider (IdP)

-

In organizations leveraging Microsoft Azure Active Directory (Azure AD) for identity and access management (IAM), integrating it with Choreo offers powerful API access control. This control hinges on the use of API scopes. That is, it enables the restriction of access to a designated group of users. This document guide you step-by-step to configure Azure AD as your external IdP.

-

Prerequisites

-

Before you try out this guide, be sure you have the following:

-
    -
  • An Azure Active Directory account: If you don’t already have one, setup an Azure Active Directory account at https://azure.microsoft.com/en-gb/.
    • -
  • Administrator rights to your Choreo organization: You need this to configure the Azure AD account in your organization.
    • -
-

Add Azure Active Directory as an external IdP in Choreo

-

Follow the steps below to add Azure AD as an IdP in Choreo:

-
    -
  1. Sign in to the Choreo Console at https://console.choreo.dev/.
    2. -
  2. In the left navigation menu, click Settings.
    3. -
  3. In the header, click the Organization list. This will open the organization level settings page.
    4. -
  4. On the Application Security tab, click Identity Providers and then click + Identity Provider.
    5. -
  5. Select Microsoft Entra ID (Azure AD) as the Identity Provider.
    6. -
  6. Provide a name and a description for the IdP.
    7. -
  7. -

    To obtain the Well-Known URL of your Azure AD instance, on your Azure account, under Azure Active Directory go to App registrations, and then Endpoints. Copy the URI underOpenID Connect metadata document.

    -
    -

    Info

    -
      -
    • In azure, there are two versions of access tokens available. By default, the IDP applications you create use the v1 access token. Therefore, if you intend to use the v1 access token, when providing the Well-Known URL, omit the v2.0 path segment from the URL. Learn more -For example, convert https://login.microsoftonline.com/<tenant-id>/v2.0/.well-known/openid-configuration-> https://login.microsoftonline.com/<tenant-id>/.well-known/openid-configuration
      • -
    • If you intend to work with v2.0, then the IDP application's manifest should be changed as explained in the access tokendocumentation.
      • -
    -
    -
    8. -
  8. -

    Leave the Apply to all environments checkbox selected. However, if you want to restrict the use of the external IdP to a certain environment, you can select them from the Environments list.

    -
    9. -
  9. Review the endpoints and click Next.
    10. -
- - - - - - -
-
- - -
- - - -
- - -
- - - -
-
-
- - - - - - - - - - - - - - - - - \ No newline at end of file diff --git a/en/site/administer/configure-developer-portal-self-sign-up/index.html b/en/site/administer/configure-developer-portal-self-sign-up/index.html deleted file mode 100644 index 3d79e29b4..000000000 --- a/en/site/administer/configure-developer-portal-self-sign-up/index.html +++ /dev/null @@ -1,15 +0,0 @@ - - - - - - Redirecting... - - - - - - -Redirecting... - - diff --git a/en/site/administer/configure-enterprise-login/index.html b/en/site/administer/configure-enterprise-login/index.html deleted file mode 100644 index a8a6a5539..000000000 --- a/en/site/administer/configure-enterprise-login/index.html +++ /dev/null @@ -1,3389 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - Configure Enterprise Login - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- - - -
- - - - - - -
- - -
- -
- - - - - - - -
-
- - - -
-
-
- - - - -
-
-
- - - -
-
-
- - - -
-
-
- - - -
-
- - - - - - - - - - - - - - - - - - - - -

Configure Enterprise Login

-

With Choreo, you can configure enterprise login to allow users from an external identity provider (IdP) to sign in to Choreo seamlessly without changing their credentials.

-

This guide walks you through the steps to configure enterprise login for your organization in Choreo.

-

Prerequisites

-

Before you proceed with the configuration, set up the following:

-
    -
  • A valid email domain for your organization.
    • -
  • Access the Choreo Console at https://console.choreo.dev/ via your Google, GitHub, or Microsoft account. If you are a new user, create an organization with a unique organization name. For example, "Stark Industries".
    • -
-

Configure enterprise login for your Choreo organization

-

To configure enterprise login for your Choreo organization, follow the steps given below:

-
    -
  • -

    If you already have a support account with us, send us your organization name/handle and the email domains specific to your organization through our support portal.

    -
    • -
  • -

    If you do not have a support account with us yet, send an email to choreo-help@wso2.com requesting to enable enterprise login for your organization.

    -
    -

    Tip

    -

    Ensure you include the following information in the request:

    -
      -
    • Organization name or handle. For example, “Stark Industries” or “starkindustries”.
      • -
    • Email domains specific to your organization. For example, “@stark.com”, “@starkindustries.com”, and “@stark.eu.
      • -
    -
    -
    -

    Sample email

    -

    Subject : [Stark Industries] Configure enterprise login

    -

    Hi CS team,

    -

    I need to configure enterprise login for my organization. Can you please do the necessary configurations to proceed?

    -

    My organization details are as follows:

    -
      -
    • Organization name: Stark Industries
      • -
    • Organization handle: starkindustries
      • -
    • Email domains specific to my organization: “@stark.com”, “@starkindustries.com”, and “@stark.eu”
      • -
    -

    Thank you.

    -
    -

    The Choreo support team will perform the necessary configurations and respond to you with a verification code. You must sign in to your domain host account and configure the DNS record for your email domain with the following values:

    - - - - - - - - - - - - - - - - - - - - - -
    FieldValue
    Name/Host/AliasSpecify @ or leave it blank
    Time to Live (TTL)Keep the default value or use 86400
    Value/Answer/Destinationwso2-domain-verification:<verification_code>
    -
    • -
-

Now, you are ready to bring your own identity to Choreo.

-

Bring your own identity to Choreo

-

When you create an organization in Choreo, an organization with the same name is provisioned for you in Asgardeo. To bring your own identity to Choreo, you must configure a federated enterprise IdP on Asgardeo in the organization that is provisioned for you.

-

Follow the steps given below to configure the federated IdP:

-
    -
  1. Sign in to Asgardeo.
    2. -
  2. To configure a federated enterprise identity provider for your Asgardeo organization, follow the steps in Asgardeo documentation - Add Standard-Based Login.
    3. -
  3. In the Asgardeo Console left navigation menu, click Applications. You will see an application named WSO2_LOGIN_FOR_CHOREO_CONSOLE.
    4. -
  4. Click on the application to edit it.
    5. -
  5. Click the Sign-in Method tab. You can observe the configured connection.
    6. -
-

Now, users in your enterprise IdP can sign in to the Choreo Console using their enterprise IDs.

-

Configure role-based access control for enterprise login

-

To streamline the enterprise login process and grant appropriate permission, Choreo provides the flexibility to configure role-based access control for users who reside in an external IdP.

-

To set up role-based access control for enterprise login within Choreo, follow the steps given below:

-

Prerequisites

-

Before you proceed with the configuration, make sure you complete the following:

-
    -
  1. Configure enterprise login for your organization. For instructions, see Configure enterprise login for your Choreo organization.
    2. -
  2. Ensure your enterprise identity provider includes the group/role attributes in tokens it sends to Asgardeo via the respective protocol.
    3. -
  3. Be sure you have administrator privileges in Choreo.
    4. -
-

Step 1: Configure Asgardeo

-
    -
  1. Sign in to Asgardeo.
    2. -
  2. -

    Configure your IdP as an external IdP in Asgardeo. Depending on your IdP, you can select OpenID Connect or SAML as the protocol between Asgardeo and your IdP.

    -
    -

    Note

    -

    If you are using OpenID Connect, configure the requested scopes accordingly for Asgardeo to get the relevant group/role details from the external IdP.

    -
    -
    3. -
  3. -

    To configure the application, follow the steps given below:

    -
      -
    1. In the Asgardeo Console left navigation menu, click Applications. You will see an application named WSO2_LOGIN_FOR_CHOREO_CONSOLE.
      2. -
    2. Click on the application to edit it.
      3. -
    3. Click the Sign-in Method tab.
      4. -
    4. -

      Configure the IdP for login depending on the protocol you selected:

      - -
      5. -
    5. -

      Click the User Attributes tab.

      -
      6. -
    6. Select the Groups attribute and click the arrow to expand the section. Then, select the Requested checkbox.
      7. -
    7. Click Update.
      8. -
    -
    4. -
  4. -

    To add the user attributes as OpenID Connect scopes, follow the steps given below:

    -
      -
    1. In the Asgardeo Console left navigation menu, click Scopes.
      2. -
    2. In the OpenID Connect Scopes pane, click OpenID to edit it.
      3. -
    3. Click New Attribute and select the Groups attribute.
      4. -
    4. Click Save and then click Save Changes.
      5. -
    -
    5. -
-

Step 2: Map Choreo groups to enterprise IdP groups via the Choreo Console

-
-

Note

-

Before you map Choreo groups to enterprise IdP groups, ensure you meet the following criteria:

-
    -
  • Asgardeo is your key manager.
    • -
  • You have permission to perform actions of the organization administrator role.
    • -
-
-
    -
  1. Sign in to the Choreo Console.
    2. -
  2. In the Choreo Console, go to the top navigation menu and click Organization. This takes you to the organization's home page.
    3. -
  3. In the left navigation menu, click Settings. This opens the organization-level settings page.
    4. -
  4. In the Access Control tab, click Groups.
    5. -
  5. -

    Click Manage IdP Group Mapping. - Group mapping

    -
    6. -
  6. -

    Click the edit icon corresponding to the Choreo group you want to map to the enterprise IdP group.

    -
    7. -
  7. -

    In the IdP Group Name field, specify the exact name you configured in the enterprise IdP and enter to add it.

    -
    -

    Tip

    -

    If there is a change to the IdP group mapping, it takes effect from the next login session onwards.

    -
    -
    8. -
  8. -

    Click Save.

    -
    9. -
-

By following these steps, you have successfully configured role-based access control for enterprise login in Choreo, allowing users from the external IdP to have the appropriate permission.

- - - - - - -
-
- - -
- - - -
- - -
- - - -
-
-
- - - - - - - - - - - - - - - - - \ No newline at end of file diff --git a/en/site/administer/configure-self-sign-up/index.html b/en/site/administer/configure-self-sign-up/index.html deleted file mode 100644 index fad1a699b..000000000 --- a/en/site/administer/configure-self-sign-up/index.html +++ /dev/null @@ -1,3350 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - Configure Self-Sign-Up - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- - - -
- - - - - - -
- - -
- -
- - - - - - - -
-
- - - -
-
-
- - - - -
-
-
- - - -
-
-
- - - -
-
-
- - - -
-
- - - - - - - - - - - - - - - - - - - - -

Configure Self-Sign-Up

-

With Choreo, you can set up a self-sign-up page for your Developer Portal. The self-sign-up page allows users to easily access your Developer Portal and subscribe to APIs. When you configure self-sign-up, users can create their accounts and access your Developer Portal without any manual intervention from you.

-

This page walks you through the steps to configure self-sign-up for your Developer Portal.

-

Prerequisites

-
    -
  1. Sign in to the Choreo Console at https://console.choreo.dev/ using your Google, GitHub, or Microsoft account.
    2. -
  2. If you are a new user, create an organization with a unique organization name. For example, "Stark Industries".
    3. -
-

Configure Developer Portal self-sign-up

-

To configure self-sign-up, follow the steps given below:

-
    -
  1. -

    Send an email to choreo-help@wso2.com requesting to configure enterprise IdP for the Developer Portal of your organization.

    -
    -

    Tip

    -

    Ensure you include the organization name or handle in the request.

    -
    -
    -

    Sample email

    -

    Subject : [Stark Industries] Configure enterprise IdP for Developer Portal

    -

    Hi CS team,

    -

    I need to configure enterprise IdP for my organization’s Developer Portal to enable self-sign-up. Can you please do the necessary configurations to proceed?

    -

    My organization details are as follows:

    -
      -
    • Organization name: Stark Industries
      • -
    • Organization handle: starkindustries
      • -
    -

    Thank you

    -
    -

    The Choreo support team will perform the necessary configurations and respond to your request.

    -
    2. -
  2. -

    When you receive a response, sign in to Asgardeo using the same credentials that you used to sign in to Choreo.

    -
    3. -
  3. -

    In the Asgardeo Console, click View all applications.

    -

    View all applications

    -

    You will see an application named WSO2_LOGIN_FOR_CHOREO_DEV_PORTAL.

    -

    Applications

    -
    4. -
  4. -

    Click on the application to edit it and enter your organization’s Developer Portal URL as the Access URL of the application. For example, https://devportal.choreo.dev/starkindustries.

    -
    5. -
  5. Click Update.
    6. -
  6. -

    To add user attributes, follow these steps:

    -
    -

    Note

    -

    If you have enabled enterprise login and you want to add the Groups attribute during self-sign-up configuration, avoid making it mandatory. This ensures proper access control and prevents unauthorized privileges. If you make the Groups attribute mandatory, it allows self-signed-up users to specify a group and assume roles associated with it.

    -
    -
      -
    1. Click the User Attributes tab.
      2. -
    2. -

      To add the email as a mandatory user attribute, select Email and click the arrow to expand the section. Then, select the Requested and Mandatory checkboxes.

      -

      Email attribute

      -
      3. -
    3. -

      To add the first name and last name as optional attributes, select Profile and click the arrow to expand the section. Then, select the Requested checkbox for the First Name and the Last Name attributes.

      -

      Profile attribute

      -
      4. -
    4. -

      Click Update.

      -
      5. -
    -
    7. -
  7. -

    To add the user attributes as OpenID Connect scopes, follow these steps:

    -
      -
    1. In the Asgardeo Console left navigation menu, click Scopes.
      2. -
    2. In the OpenID Connect Scopes pane, click OpenID to edit it.
      3. -
    3. Click + New Attribute.
      4. -
    4. Select Email, First Name, and Last Name as the attributes to associate with the OpenID scope.
      5. -
    5. -

      Click Save and then click Save Changes.

      -

      Save attributes as scopes

      -
      6. -
    -
    8. -
  8. -

    To configure basic authentication as the sign-in method, follow these steps:

    -
      -
    1. In the Asgardeo Console left navigation menu, click Applications.
      2. -
    2. In the Applications pane, click the WSO2_LOGIN_FOR_CHOREO_DEV_PORTAL application to edit it.
      3. -
    3. -

      Click the Sign-in Method tab and then click Start with default configuration.

      -

      Add sign-in method

      -
      4. -
    4. -

      Click Update.

      -
      5. -
    -
    9. -
  9. -

    To configure self-registration, follow these steps:

    -
      -
    1. In the Asgardeo Console left navigation menu, click Self Registration.
      2. -
    2. In the Self Registration pane, click Configure.
      3. -
    3. To enable self-registration, turn on the toggle.
      4. -
    4. Select Account verification. This displays a confirmation message to enable account verification.
      5. -
    5. Click Continue.
      6. -
    6. Specify an appropriate value in the Account verification link expiry time field.
      7. -
    7. -

      Click Update.

      -

      Configure self-registration

      -
      8. -
    -
    10. -
-

Once you complete these steps, you will see a sign up link similar to the following in your Developer Portal:

-

Sign-up

-

Users can click LOGIN/SIGN UP and then click Create an account to sign up to access your Developer Portal.

-

Create an account

-

Manage new users

-

To manage users who want to access your Developer Portal via self-sign-up, you have two possible approaches:

-
    -
  • Enable auto-approval for new user registrations: This approach automates the user approval process. When you enable auto-approval, each user who creates an account and signs up to your Developer Portal can access it by default.
    • -
  • Manually approve or reject user accounts: This allows you to review the list of user registrations and manually approve or reject each registration as needed.
    • -
-

Enable auto-approval for new user registrations

-

To automatically approve each new user account registered on your Developer Portal, follow the steps given below:

-
    -
  1. In the Choreo Console, click your username in the top right corner.
    2. -
  2. In the drop-down menu, click Settings. This opens the Organization pane, where you can make necessary changes to organization settings.
    3. -
  3. In the Organization pane, click Self Signups.
    4. -
  4. To enable auto-approval, turn on the toggle.
    5. -
-

Once you enable auto-approval, users can sign in to your Developer Portal and view your APIs and applications immediately after creating an account.

-

Manually approve or reject user accounts

-

If you have not enabled auto-approval, you can manually approve or reject new user registrations. Once a user creates an account, Choreo sends an email to ask the user to confirm the account. To manually approve or reject user accounts, follow the steps given below:

-
    -
  1. In the Choreo Console, click your username in the top right corner.
    2. -
  2. In the drop-down menu, click Settings. This opens the Organization pane, where you can make necessary changes to organization settings.
    3. -
  3. In the Organization pane, click Self Signups. You will see the user accounts listed for approval.
    4. -
  4. -

    To approve a user account, click Approve. To reject an account, click Reject.

    -
      -
    • If you approve an account, the user will receive an email confirming the approval.
      • -
    • -

      If you reject an account, the user will receive an email mentioning that their account is rejected.

      -
      -

      Note

      -

      A rejected user cannot sign up to your Developer Portal using the same account again.

      -
      -
      • -
    -
    5. -
- - - - - - -
-
- - -
- - - -
- - -
- - - -
-
-
- - - - - - - - - - - - - - - - - \ No newline at end of file diff --git a/en/site/administer/connect-to-an-external-identity-provider/index.html b/en/site/administer/connect-to-an-external-identity-provider/index.html deleted file mode 100644 index 01f424356..000000000 --- a/en/site/administer/connect-to-an-external-identity-provider/index.html +++ /dev/null @@ -1,15 +0,0 @@ - - - - - - Redirecting... - - - - - - -Redirecting... - - diff --git a/en/site/administer/control-access-in-the-choreo-console/index.html b/en/site/administer/control-access-in-the-choreo-console/index.html deleted file mode 100644 index c9de8b517..000000000 --- a/en/site/administer/control-access-in-the-choreo-console/index.html +++ /dev/null @@ -1,3363 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - Control Access in the Choreo Console - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- - - -
- - - - - - -
- - -
- -
- - - - - - - -
-
- - - -
-
-
- - - - -
-
-
- - - -
-
-
- - - -
-
-
- - - -
-
- - - - - - - - - - - - - - - - - - - - -

Control Access in the Choreo Console

-

In the Choreo Console, you have the ability to manage access to projects and the actions that can be performed within them. Administrators have the capability to restrict project access to specific user groups. This feature is useful when you need certain user groups to have access to particular projects or for a set of projects.

-

Choreo uses Roles, Groups, and a Mapping level to control access to the Choreo Console as follows:

-
    -
  • Role : Role is a collection of permissions. Choreo has a predefined set of roles with permissions assigned to them. Learn more
    • -
  • -

    Group : Group is a collection of users. A user group requires a role or multiple roles to be assigned to it so that the users in those groups get the relevant permissions via the assigned roles. Learn more

    -
    • -
  • -

    Mapping level : A mapping level defines the extent at which a role-group mapping can be done. Choreo has two defined resource levels.

    -
      -
    • Organization : You can assign a role to a group or associate a group with a role within the organization. This ensures that
      - all users in a group inherit the permissions granted by that role across all organizational resources. - For example, if a user has edit_project permission at the organization mapping level, that user can edit all the projects in the organization.
      • -
    • Project : You can assign a role to a group or associate a group with a role within a specific project resource. This ensures - that users in the group inherit the permissions granted by that role only within the context of the specified project. - For example, If a user has edit_project permission at the project mapping level, that user can only edit the specified project.
      • -
    -
    • -
-

In Choreo, authorization operates by assigning a role to a group at a specified level. The level at which the role is assigned determines the extent of permissions granted to users.

-
-

Important

-

Avoid assigning multiple roles to a single user across different projects or levels (organization and project). Such assignments can grant users unintended permission to some projects, allowing them to perform tasks they shouldn't have access to. Therefore, it is recommended to assign only one role to a user across projects or levels to ensure proper access control.

-
-
-

Info

-

In Choreo, organization-level permissions take precedence over project-level permissions.

-
-

To elaborate further, refer to the following diagram.

-

The following diagram depicts a role-group assignment at a specific resource level. In the diagram, an admin user has assigned the Developer role to all members of the Engineering group within the Engineering Project. This grants users in the Engineering group the ability to perform all actions allowed by the Developer role within the Engineering Project.

-

Console access control

-

Sample scenario

-

Now that you understand the basic concepts of access control within the Choreo Console, let’s try out a sample scenario to manage access within a project.

-

Assume you are overseeing the Engineering Project within your organization and you need to grant development access to specific users solely within this project. Here's a step-by-step guide on how to achieve this:

-

Step 1: Create a project

-

Follow the steps given below to create a project:

-
    -
  1. Go to https://console.choreo.dev/ and sign in. This opens the organization home page.
    2. -
  2. On the organization home page, click + Create Project.
    3. -
  3. -

    Enter a display name, unique name, and description for the project. You can enter the values given below:

    -
    -

    Info

    -

    In the Name field, you must specify a name to uniquely identify your project in various contexts. The value is editable only at the time you create the project. You cannot change the name after you create the project.

    -
    - - - - - - - - - - - - - - - - - - - - - -
    FieldValue
    Project Display NameEngineering Project
    Nameengineering-project
    Project DescriptionMy sample project
    -
    4. -
  4. -

    Click Create. This creates the project and takes you to the project home page.

    -
    5. -
-

Step 2: Create a new group

-

Follow the steps given below to create a group with the name Engineering Project Developer:

-
    -
  1. In the Choreo Console, go to the top navigation menu, click the Organization list, and select the organization where you created your project.
    2. -
  2. In the left navigation menu, click Settings.
    3. -
  3. Click the Access Control tab and then click the Groups tab.
    4. -
  4. Click + Create Group.
    5. -
  5. -

    Enter a group name and group description. You can enter the values given below:

    - - - - - - - - - - - - - - - - - -
    FieldValue
    Group NameEngineering Project Developer
    Group DescriptionUsers with development access within the engineering project
    -
    6. -
  6. -

    Click Create.

    -
    7. -
-

Step 3: Assign roles to the group

-

Follow the steps given below to assign the Developer role to the Engineering Project Developer group that you created:

-
    -
  1. In the Choreo Console, go to the top navigation menu, click the Project list, and select the Engineering Project that you created.
    2. -
  2. In the left navigation menu, click Settings.
    3. -
  3. Click the Access Control tab and then click the Groups tab.
    4. -
  4. On the Groups tab, search for the Engineering Project Developer group and click the corresponding edit icon.
    5. -
  5. Click +Add Roles.
    6. -
  6. In the Add Roles to Group in Project dialog that opens, click the Roles list and select Developer.
    7. -
  7. -

    Click Add. This assigns the Developer role to the group. You should see the mapping level as Project (Engineering Project) as follows, indicating the scope of the mapping:

    -

    Mapping level

    -
    8. -
-

This means that you have granted developer access to users in the Engineering Project Developer group in the scope of the Engineering Project.

-

Now that you have set up access control, you can proceed to add users to the new group.

-

Step 4: Add users to the group

-

There are two approaches you can follow to add users to the group.

-

Add a new user as a project developer

-

Follow the steps given below to add a new user as a project developer:

-
    -
  1. In the Choreo Console, go to the top navigation menu, click the Organization list, and select the organization where you created your project.
    2. -
  2. In the left navigation menu, click Settings.
    3. -
  3. Click the Access Control tab and then click the Users tab.
    4. -
  4. Click +Invite Users.
    5. -
  5. In the Invite Users dialog,
    6. -
  6. Specify the email addresses of the users in the Emails field.
    7. -
  7. Click the Groups list and select Engineering Project Developer.
    8. -
  8. Click Invite.
    9. -
-

Add an existing user as a project developer

-

Follow the steps given below to add an existing user as a project developer:

-
    -
  1. In the Choreo Console, go to the top navigation menu, click the Organization list, and select the organization where you created your project.
    2. -
  2. In the left navigation menu, click Settings.
    3. -
  3. Click the Access Control tab and then click the Users tab.
    4. -
  4. Search for the existing user you want to add to the Engineering Project Developer group.
    5. -
  5. Click the edit icon corresponding to the user.
    6. -
  6. Click +Assign Groups.
    7. -
  7. In the Add Groups to User dialog, click the Groups list and select Engineering Project Developer.
    8. -
  8. Click Add.
    9. -
-
-

Tip

-

Make sure to remove the user from any other groups to avoid granting organization-level access unintentionally.

-
-
-

Note

-
    -
  • Existing groups are already mapped to similar roles at the organization level. Therefore, adding users to those groups or keeping users in them, will give organization-level access to the users.
    • -
  • When users are added to the Engineering Project Developer group, they will only have developer access to the Engineering Project.
    • -
  • You can invite new users or add existing users to new groups within the Engineering Project, and based on their requirements, assign roles like Developer, API Publisher, etc.
    • -
-
-

Now you have successfully set up access control within your project.

- - - - - - -
-
- - -
- - - -
- - -
- - - -
-
-
- - - - - - - - - - - - - - - - - \ No newline at end of file diff --git a/en/site/administer/create-api-subscription-plans/index.html b/en/site/administer/create-api-subscription-plans/index.html deleted file mode 100644 index 6045f9fc1..000000000 --- a/en/site/administer/create-api-subscription-plans/index.html +++ /dev/null @@ -1,3120 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - Create API Subscription Plans - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- - - -
- - - - - - -
- - -
- -
- - - - - - - -
-
- - - -
-
-
- - - - -
-
-
- - - -
-
-
- - - -
-
-
- - - -
-
- - - - - - - - - - - - - - - - - - - - -

Create API Subscription Plans

-

API subscription plans are essential to control and manage access to APIs. These plans define the rules and limitations on how clients can interact with APIs, ensuring efficient resource utilization and robust security. With the option to set rate limits and burst control, subscription plans allow API providers to manage traffic, prevent misuse, and offer tiered service levels. Organizations can implement subscription plans to provide varying levels of API access, accommodating different user needs and business models, while ensuring optimal performance and security.

-

In Choreo, users with the administrator role can create, update, and delete subscription plans at the organization level.

-
-

Tip

-

Deleting a subscription plan is only possible if there are no active subscriptions associated with it.

-
-

To create an organization-level subscription plan, follow the steps given below:

-
    -
  1. Sign in to the Choreo Console.
    2. -
  2. In the Choreo Console header, go to the Organization list and select your organization.
    3. -
  3. In the left navigation menu, click Settings. This opens the organization-level settings page.
    4. -
  4. Click the API Management tab and then click Subscription Plans.
    5. -
  5. Click + Add Subscription Plan.
    6. -
  6. -

    In the Create Subscription Plan pane, enter the appropriate values for each field:

    -
    -

    Note

    -
      -
    • In the Name field, you must specify a name to uniquely identify the subscription plan in various contexts. The value is editable only at the time you create the subscription plan. You cannot change the name after you create it.
      • -
    • The Stop on Quota Reach checkbox is selected by default when creating a subscription plan. When selected, requests return an HTTP 429 response if the request count exceeds the limit. If you clear the checkbox, requests are allowed even if the quota is exceeded.
      • -
    • Burst control protects your backend from sudden request spikes and manages API usage. It’s especially useful for subscription plans where the request count is enforced over a long period, to prevent consumers from using their entire quota too quickly. Ensure you select the Burst Control checkbox when the Request Count Time Unit is selected as Hour or Day.
      • -
    -
    -

    Create subscription plan

    -
    7. -
  7. -

    Click Create. This creates the subscription plan and lists it under Subscription Plans.

    -
    8. -
-

After creating subscription plans, users with the API publisher role can assign subscription plans to APIs. API consumers can then choose the appropriate subscription plan during the subscription process depending on their requirements.

- - - - - - -
-
- - -
- - - -
- - -
- - - -
-
-
- - - - - - - - - - - - - - - - - \ No newline at end of file diff --git a/en/site/administer/customize-developer-portal-domain/index.html b/en/site/administer/customize-developer-portal-domain/index.html deleted file mode 100644 index 653fc71a6..000000000 --- a/en/site/administer/customize-developer-portal-domain/index.html +++ /dev/null @@ -1,15 +0,0 @@ - - - - - - Redirecting... - - - - - - -Redirecting... - - diff --git a/en/site/administer/customize-the-developer-portal/index.html b/en/site/administer/customize-the-developer-portal/index.html deleted file mode 100644 index 089e7e872..000000000 --- a/en/site/administer/customize-the-developer-portal/index.html +++ /dev/null @@ -1,3202 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - Customize the Developer Portal - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- - - -
- - - - - - -
- - -
- -
- - - - - - - -
-
- - - -
-
-
- - - - -
-
-
- - - -
-
-
- - - -
-
-
- - - -
-
- - - - - - - - - - - - - - - - - - - - -

Customize the Developer Portal

-

The Developer Portal allows API consumers to find and consume APIs with ease. You can change the look and feel of your Developer Portal by changing the theme to match your brand. Doing so will help you give a better developer experience to your users.

-

To customize the Developer Portal theme, follow the steps given below:

-
-

Note

-
    -
  • To customize the Developer Portal theme for an organization, you need to be an admin user of that organization.
    • -
  • You cannot undo a change and restore or revert to a previous version of the theme. However, you can reset it to the default theme.
    • -
-
-
    -
  1. -

    Sign in to the Choreo Console at https://console.choreo.dev/ using a Google/ GitHub/ Microsoft account.

    -
    2. -
  2. -

    In the left pane, click Settings.

    -
    3. -
  3. -

    In the header, click the Organization list. This will open the organization level settings page.

    -
    4. -
  4. -

    In the API Management tab, click Devportal Theme.

    -

    Access Devportal theme

    -

    Once you access the theme, you can customize the Home page, color theme, font, header and footer, logos, etc., by expanding the relevant sections.

    -
    5. -
  5. -

    Make a change to the theme. For example, let's change the title on the Home page and the color theme.

    -
      -
    1. -

      To update the title on the Home page, expand the Home Page section, and in the Title field, change the default text (for example, to Try our APIs!).

      -
      2. -
    2. -

      To update the color theme, expand the Color Palette section, and change the colors as required (for example, change the background color to #C3C5CD and the primary color of the buttons to #086634).

      -
      3. -
    3. -

      Click Preview to view a preview of the Developer Portal with the changes you made. Based on the changes given in the examples, the preview appears as follows.

      -

      Preview of customization

      -
      4. -
    4. -

      Click Save to save your changes as a draft theme.

      -
      5. -
    5. -

      To apply the changes to the Developer Portal, toggle the Go Live switch. To confirm that you want to go live with the changes, click Enable in the message that appears.

      -
      6. -
    -
    6. -
  6. -

    Sign in to the Choreo Developer Portal at https://devportal.choreo.dev.

    -
    7. -
-

The Home page will appear as it did in the preview.

-

Reset the Developer Portal theme

-

To reset the Developer Portal theme to the default theme, follow the steps given below:

-
    -
  1. -

    Sign in to the Choreo Console at https://console.choreo.dev/ using a Google, GitHub, or Microsoft account.

    -
    2. -
  2. -

    In the left pane, click Settings.

    -
    3. -
  3. -

    In the header, click the Organization list. This will open the organization level settings page.

    -
    4. -
  4. -

    In the Organization tab, click Devportal Theme, and then click Reset to Default.

    -
    5. -
- - - - - - -
-
- - -
- - - -
- - -
- - - -
-
-
- - - - - - - - - - - - - - - - - \ No newline at end of file diff --git a/en/site/administer/inviting-members/index.html b/en/site/administer/inviting-members/index.html deleted file mode 100644 index 09ca04a80..000000000 --- a/en/site/administer/inviting-members/index.html +++ /dev/null @@ -1,3056 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - Inviting members - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- - - -
- - - - - - -
- - -
- -
- - - - - - - -
-
- - - -
-
-
- - - - -
-
-
- - - -
-
-
- - - -
-
-
- - - -
-
- - - - - - - - - - - - - - - - - - - - -

Inviting members

- -

Inviting users

-

An organization administrator can invite users to the organization by assigning them specific groups. Invited users receive an invitation via email. An invited user must accept the invitation to join the organization and access the resources of that organization.

- - - - - - -
-
- - -
- - - -
- - -
- -
-
-
-
- Copyright © WSO2 LLC (2023-2024) -
-
- Content licensed under CC By 4.0. | Sample code - licensed under Apache 2.0. -
-
-
-
-
- - - -
-
-
- - - - - - - - - - - - - - - - - \ No newline at end of file diff --git a/en/site/administer/manage-members-of-an-organization/index.html b/en/site/administer/manage-members-of-an-organization/index.html deleted file mode 100644 index d82577951..000000000 --- a/en/site/administer/manage-members-of-an-organization/index.html +++ /dev/null @@ -1,3155 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - Manage Members of an Organization - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- - - -
- - - - - - -
- - -
- -
- - - - - - - -
-
- - - -
-
-
- - - - -
-
-
- - - -
-
-
- - - -
-
-
- - - -
-
- - - - - - - - - - - - - - - - - - - - -

Manage Members of an Organization

-

An organization in Choreo is a logical grouping of users and user resources. A first-time user must create an organization and be a user of it when signing in to Choreo. Users and resources in an organization cannot access resources in another organization unless an admin of the other organization invites them and adds them as a user of that organization.

-

Inviting users

-

An organization administrator can invite users to the organization by assigning them specific groups. Invited users receive an invitation via email. An invited user must accept the invitation to join the organization and access the resources of that organization.

-

Manage user permission

-

For details on how Choreo manages user permission, see Manage user permission.

- - - - - - -
-
- - -
- - - -
- - -
- - - -
-
-
- - - - - - - - - - - - - - - - - \ No newline at end of file diff --git a/en/site/administer/organization/index.html b/en/site/administer/organization/index.html deleted file mode 100644 index 82641658e..000000000 --- a/en/site/administer/organization/index.html +++ /dev/null @@ -1,15 +0,0 @@ - - - - - - Redirecting... - - - - - - -Redirecting... - - diff --git a/en/site/administration/configure-a-custom-domain-for-apis/index.html b/en/site/administration/configure-a-custom-domain-for-apis/index.html deleted file mode 100644 index a7c3b5851..000000000 --- a/en/site/administration/configure-a-custom-domain-for-apis/index.html +++ /dev/null @@ -1,15 +0,0 @@ - - - - - - Redirecting... - - - - - - -Redirecting... - - diff --git a/en/site/administration/configure-developer-portal-self-sign-up/index.html b/en/site/administration/configure-developer-portal-self-sign-up/index.html deleted file mode 100644 index d68d964cb..000000000 --- a/en/site/administration/configure-developer-portal-self-sign-up/index.html +++ /dev/null @@ -1,15 +0,0 @@ - - - - - - Redirecting... - - - - - - -Redirecting... - - diff --git a/en/site/administration/configure-enterprise-login/index.html b/en/site/administration/configure-enterprise-login/index.html deleted file mode 100644 index e566507ef..000000000 --- a/en/site/administration/configure-enterprise-login/index.html +++ /dev/null @@ -1,15 +0,0 @@ - - - - - - Redirecting... - - - - - - -Redirecting... - - diff --git a/en/site/administration/connect-to-an-external-identity-provider/index.html b/en/site/administration/connect-to-an-external-identity-provider/index.html deleted file mode 100644 index f37f89935..000000000 --- a/en/site/administration/connect-to-an-external-identity-provider/index.html +++ /dev/null @@ -1,15 +0,0 @@ - - - - - - Redirecting... - - - - - - -Redirecting... - - diff --git a/en/site/administration/customize-developer-portal-domain/index.html b/en/site/administration/customize-developer-portal-domain/index.html deleted file mode 100644 index 732772748..000000000 --- a/en/site/administration/customize-developer-portal-domain/index.html +++ /dev/null @@ -1,15 +0,0 @@ - - - - - - Redirecting... - - - - - - -Redirecting... - - diff --git a/en/site/administration/customize-the-developer-portal/index.html b/en/site/administration/customize-the-developer-portal/index.html deleted file mode 100644 index dd3604461..000000000 --- a/en/site/administration/customize-the-developer-portal/index.html +++ /dev/null @@ -1,15 +0,0 @@ - - - - - - Redirecting... - - - - - - -Redirecting... - - diff --git a/en/site/alerts/index.html b/en/site/alerts/index.html deleted file mode 100644 index 17db144ab..000000000 --- a/en/site/alerts/index.html +++ /dev/null @@ -1,15 +0,0 @@ - - - - - - Redirecting... - - - - - - -Redirecting... - - diff --git a/en/site/api-management/api-policies/index.html b/en/site/api-management/api-policies/index.html deleted file mode 100644 index 84a89fcce..000000000 --- a/en/site/api-management/api-policies/index.html +++ /dev/null @@ -1,3692 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - API Policies - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- - - -
- - - - - - -
- - -
- -
- - - - - - - -
-
- - - -
-
-
- - - - -
-
-
- - - -
-
-
- - - -
-
-
- - - -
-
- - - - - - - - - - - - - - - - - - - - -

API Policies

-

API policies are units of business logic that you can apply to modify the flow of API invocations.

-

You can apply a policy to alter the Request, Response, or Error flow of an API invocation before it reaches the backend or the client. For example, you can add a policy to the response flow to transform the payload from JSON to XML and add a header to the response.

-

Inbuilt mediation policies

-

Choreo supports a set of inbuilt mediation policies that can handle common API transformation and mediation tasks. These policies run within a single mediation service, making it straightforward to implement and manage complex mediation logic. The following inbuilt policies are available in Choreo:

-
    -
  • JSON to XML: Transforms a JSON payload in a request or response into XML format. This policy is applicable only to JSON payloads in mediation flows. Applying it to a non-JSON payload terminates the flow. This policy cannot be used more than once on the same resource because the payload will already be converted to XML.
    • -
  • XML to JSON: Converts an XML payload in a request or response into JSON format. This policy is applicable only to XML payloads in mediation flows. Applying it to a non-XML payload terminates the flow. This policy cannot be used more than once on the same resource because the payload will already be converted to JSON.
    • -
  • Remove Query Parameter: Removes specified query parameters from a request. You can use this policy multiple times to remove different parameters. Attempting to remove a non-existent parameter has no effect. If the parameter exists, it will be removed; otherwise, the request proceeds as usual.
    • -
  • Remove Header: Removes specified headers from a request or response. You can attach this policy multiple times to remove multiple headers. The header name must be static, but you can use placeholders to configure different values for different environments. For example, ${headerName}.
    • -
  • Add Query Parameter: Adds query parameters to a request. You can attach this policy multiple times to add various parameters. Adding the same parameter multiple times creates an array of values. The parameter name and value must be static, but you can use placeholders to configure different values for different environments. For example, ${fooValue}.
    • -
  • Add Header: Adds headers to a request or response. If the same header is added multiple times, values are appended rather than overwritten. The header name and value must be static, but you can use placeholders to configure different values for different environments. For example, ${authzHeaderValue}.
    • -
  • Set Header: Sets headers in a request or response, overwriting any existing values. You can attach this policy multiple times to set multiple headers. Each time the same header is set, it replaces the previous value. The header name and value must be static, but you can use placeholders to configure different values for different environments. For example, ${authzHeaderValue}.
    • -
  • Rewrite Resource Path: Modifies the resource path of an HTTP request by replacing the original path with a new relative path. You can apply this policy multiple times, but only the last instance will take effect. The new path must be static, but you can use placeholders to configure different values for different environments. For example, ${myResourcePath}.
    • -
  • Log Message: Logs the payload and headers of a request or response. Attaching this policy multiple times results in duplicate log entries. By default, headers and payloads are not logged. To log them, you can enable Log Headers and Log Payload parameters. To exclude specific headers when logging, you can use the Excluded Headers parameter, which takes a comma-separated list of header names. An error will occur if payload logging is enabled but the payload cannot be read.
    • -
-

These inbuilt mediation policies provide flexibility to manage API requests and responses, allowing for custom transformations and logic without requiring custom code.

-

Attach and manage mediation policies

-

You can easily attach one or more policies to an API proxy component implementation via the Choreo Console. If necessary, you can also rearrange or swap the policies you attach.

-

In Choreo, when you attach a mediation policy to a proxy, the deployment is a two-step process.

-
    -
  1. -

    Deployment initiation:

    -

    If the component to which you want to attach the mediation policy is new, the system creates and commits a new repository with the mediation service code based on the attached policy. This new service is called the mediation application.

    -
    2. -
  2. -

    Deploying the API:

    -

    Once the deployment initiation is complete, you can specify configuration values if any, and proceed to deploy. Choreo builds the generated mediation application and pushes the Docker image to the Docker registry. Finally, Choreo deploys the mediation application with the API Proxy.

    -
    3. -
-

When a mediation policy is attached to a specific flow, the API invocation undergoes the following behavioral modification:

-

Request/Response flow

-
    -
  • -

    In the request path, the requests that pass through the gateway reach the relevant component, and Choreo executes any attached policies to the resource's request path before sending it to the backend.

    -
    • -
  • -

    In the response path, the mediation component receives response messages from the backend, and Choreo executes any mediation policies attached to the Response flow or the Error flow. Then the response is forwarded to the client.

    -
    • -
  • -

    If an error occurs during the execution of policies or due to an internal error, Choreo executes the Error flow and sends an error response to the client.

    -
    • -
-

Attach a policy

-

To attach a policy to the Request, Response, or Error flow of a REST API proxy, follow the steps given below:

-
    -
  1. Sign in to the Choreo Console.
    2. -
  2. In the Component Listing pane, click on the REST API Proxy component for which you want to attach a policy.
    3. -
  3. In the left navigation menu, click Develop and then click Policies.
    4. -
  4. From the list of resources, expand the resource to which you want to attach the policy.
    5. -
  5. Click Attach Mediation Policy in the respective flow for which you want to attach a policy.
    6. -
  6. In the Policy List pane that opens, click on a required policy to view its details.
    7. -
  7. -

    If the attached policy requires parameter configuration, on the policy pane enter the appropriate values and configure the parameters. To make a parameter a configurable variable, input the value in the ${<variableName>} format. For example, you can use ${name} as an example.

    -

    Configure parameters

    -
    8. -
  8. -

    To attach the policy, click Add.

    -
    9. -
-

After attaching an API Policy, it is necessary to deploy the API for the policy to become active within its corresponding flow. -To deploy the API follow the steps below:

-
    -
  1. -

    In the left navigation menu, click Deploy and then click Configure & Deploy. Choreo performs the mediation application generation step and opens the Configure & Deploy pane.

    -
    2. -
  2. -

    In the Configure & Deploy pane, if you have any configurable variables that require values, specify appropriate values for them.

    -

    Save and deploy values

    -
    3. -
  3. -

    Click Save & Deploy.

    -
    4. -
-

Refresh mediation policies

-

Choreo selectively generates and builds the mediation application code during component deployment depending on specific changes. These changes include:

-
    -
  • Addition, deletion, or modification of API resources.
    • -
  • Attachment, removal, or editing of API mediation policies.
    • -
  • Endpoint modifications via the Develop page.
    • -
  • Initial configuration or removal of backend endpoints or mutual TLS certificates.
    • -
-

If none of the above changes occur during deployment, Choreo skips the code generation and build process of the mediation application.

-
-

Info

-
    -
  • If you want to enforce the code generation and build process of the mediation application in instances where the specified changes do not take place, you must turn on the Refresh Mediation Policies toggle when you configure and deploy the component.
    • -
  • It is useful to enable Refresh Mediation Policies when you want to incorporate the latest Ballerina patches for your generated mediation application. However, this can result in longer deployment times.
    • -
-
-

Implement an API policy

-

Choreo allows you to implement an API policy as a Ballerina project and attach it to an API proxy component.

-
-

Info

-

Supported Ballerina version: 2201.5.5

-
-

To implement a policy, follow the steps given below:

-

Prerequisites

-
    -
  1. Set up Ballerina 2201.5.5.
    2. -
  2. Open the ~/.ballerina/settings.toml file and ensure you have configured an access token to Ballerina Central. If you have not configured an access token, follow the steps given below to configure one:
      -
    1. Generate a token via https://central.ballerina.io/dashboard?tab=token.
      2. -
    2. Download the generated Settings.toml file and copy it to your local ~/.ballerina directory.
      3. -
    -
    3. -
-

Alternatively, you can set the access token via the BALLERINA_CENTRAL_ACCESS_TOKEN environment variable.

-
export BALLERINA_CENTRAL_ACCESS_TOKEN=<access-token> 
-
- -

Step 1: Initialize a Ballerina project

-

Choreo provides a template to initialize a mediation policy project with all the required configurations. The mediation policy project will be created as a Ballerina project.

-

To create a Ballerina project for the mediation policy using mediation.template as the project template, issue the following command:

-

Format:

-
    bal new -t choreo/mediation.template:1.0.0 <policy-name> 
-
- -

Example:

-

    bal new -t choreo/mediation.template:1.0.0 validateHeader 
-
- The Ballerina project that is created should have the following content:

-

Ballerina project

-

Depending on your requirement, you can modify the Ballerina.toml and the Package.md files of the generated project. For example, you can update the org, package, package version, API documentation content, keywords, etc.

-
-

Note

-

To successfully publish to Ballerina Central, make sure you update the org value to your organization name.

-
-
     [package]
-        org = "starkindustries"
-        name = "validateHeader"
-        version = "1.0.0"
-        export = ["validateHeader"]
-        distribution = "2201.5.5"
-        keywords = ["choreo-apim-mediation-policy","choreo-apim-mediation-request-flow","choreo-apim-mediation-response-flow","choreo-apim-mediation-fault-flow"]
-
- -

Step 2: Implement the policy

-

In this step, you will implement the policy.

-

Let's assume you want to implement a policy to validate an incoming header in the request and the response.

-
    -
  • Request path: If the request header is not present or if the validation fails, you want to log an error and return a 403 Bad Request response to the client.
    • -
  • Response path: You want to log a message to indicate whether the request is valid or not.
    • -
-

To implement the policy, open the policy.bal file in the Ballerina project and update the generated policy stubs(i.e., request, response, or fault) appropriately.

-

The following sections walk you through sample implementations for the Request and Response stubs:

-

Request flow

-

The following is a sample implementation for the request flow:

-
@mediation:RequestFlow
-public function validateRequestHeader(mediation:Context ctx, http:Request req, string headerName, string headerValue) returns http:Response|false|error|() {
-   string|http:HeaderNotFoundError header = req.getHeader(headerName);
-   if (header is http:HeaderNotFoundError) {
-    string message = string `Header ${headerName} is not found`;
-    log:printError(message);
-    return generateResponse(message, http:STATUS_BAD_REQUEST);
-   }
-   if (header != headerValue) {
-    string validationFailedMessage = string `Header validation failed. Expected ${headerValue} but found ${header}`;
-    log:printError(validationFailedMessage);
-    return generateResponse(validationFailedMessage, http:STATUS_BAD_REQUEST);
-    }
-    log:printInfo("Header validation successful");
-    return ();
-};
-
-function generateResponse(string message, int statusCode) returns http:Response {
-    http:Response response = new();
-    response.setTextPayload(message); 
-    response.statusCode = statusCode;
-    return response;
-}
-
- -

Response flow

-

The following is a sample implementation for the response flow:

-
@mediation:ResponseFlow
-public function validateResponseHeader(mediation:Context ctx, http:Request req, http:Response res, string headerName, string headerValue) returns http:Response|false|error|() { 
-   string|http:HeaderNotFoundError header = res.getHeader(headerName);
-   if (header is http:HeaderNotFoundError) {
-    string message = string `Header ${headerName} is not found`;
-    log:printError(message);
-    return ();
-   }
-   if (header != headerValue) {
-    string validationFailedMessage = string `Header validation failed. Expected ${headerValue} but found ${header}`;
-    log:printError(validationFailedMessage);
-    return ();
-   }
-   return ();
-}
-
- -

Fault flow

-

In this guide, you are not going to make any changes to the Fault flow. Therefore, you can remove the Fault flow stub from the policy.bal file.

-
-

Note

-

The @mediation:RequestFlow, @mediation:ResponseFlow, and @mediation:FaultFlow annotations are bound with the keywords in the Ballerina.toml. Therefore, the changes you make to the policy stubs should reflect in the Ballerina.toml file. For example, if the policy is applicable only on the request and response paths, you can remove the @mediation:FaultFlow annotation from the policy. Then, you MUST also remove the choreo-apim-mediation-fault-flow keyword from the generated Ballerina.toml file. If you do not do so, the Ballerina compiler will show an error at compile time.

-
-

Publish as a private custom policy

-

Choreo supports publishing a policy as a private custom policy. Publishing a policy as a private custom policy makes the policy inaccessible outside of the organization. To publish a policy as a private custom policy, change the visibility to private prior to pushing the package to Ballerina Central as follows:

-
    -
  1. Open the Ballerina.toml file of your policy.
    2. -
  2. -

    Set the visibility to private by adding the configuration visibility="private". For example:

    -
    [package]
-   org = "orgName"
-   name = "packageName"
-   version = "1.0.2"
-   export = ["packageName"]
-   distribution = "2201.5.5"
-   keywords = ["choreo-apim-mediation-policy","choreo-apim-mediation-request-flow","choreo-apim-mediation-response-flow","choreo-apim-mediation-fault-flow"]
-   visibility = "private"
-
    - -
    3. -
  3. -

    Package and publish your policy to Ballerina Central.

    -
    4. -
-

Best practices

-

When implementing a policy, it is essential to follow best practices to ensure efficiency and maintainability. Here are some recommended best practices to follow:

-
    -
  • Organize the source code within the default module of the package. Do not add any additional modules.
    • -
  • A policy implementation can contain any combination of flows. A generated project contains stubs for all three flows: Request, Response, and Fault. You can remove any stub that you do not require. For example, when you create a policy that re-writes the resource paths, you can remove the Response and fault stubs.
    • -
  • The HTTP request/response objects and context record parameters gets passed as references to the policy functions. Therefore, the changes you make to these values persist throughout the policy execution and are propagated to subsequent policies. This behavior allows the request and response objects to accumulate transformations applied by attached policies.
    • -
  • Familiarize yourself with the different return types of policy flows. The following return types are unmodifiable:
      -
    • http:Response - Returns an HTTP response when you terminate the mediation flow prematurely. For example, in the in-flow sequence, the mediation sequence terminates before calling the backend. The mediation policy then sends an HTTP response to the client.
      • -
    • false - Returns false if you want to terminate the mediation sequence with a predefined response (on the Choreo side).
      • -
    • error - Returns an error if you want to terminate the mediation flow and transfer control to the fault flow. The fault flow would then construct an error response and send it to the client.
      • -
    • () - Returns () to signal the successful completion of the policy. Once the proxy has completed executing the policy, it starts to execute the next policy in the sequence.
      • -
    -
    • -
-

Step 3: Publish the policy

-

Once you implement a policy, you must publish it to Ballerina Central.

-

When you attach a policy and deploy an API, Choreo pulls the necessary packages from Ballerina Central and bundles them into the mediation application under the hood. Therefore to use policies in your APIs, you must publish them as public packages.

-

To publish the policy, follow the steps given below:

-
    -
  1. To package the policy before you publish it to Ballerina Central, issue the following command: - 
        bal pack 
-
    2. -
  2. -

    To publish the package to Ballerina Central, issue the following command:

    -
        bal push 
-
    - -
    3. -
-

Once you publish the package, it will appear as follows in the policy list:

-

Published policy

-

Write unit tests

-

You can write unit tests to test policy functions in a manner similar to how you write unit tests for a regular Ballerina function.

-

The following is a sample unit test for the validateRequestHeader function:

-
import ballerina/http;
-import choreo/mediation;
-import ballerina/test;
-
-
-@test:Config {}
-public function testRequestHeaderValidationFailure() {
-  http:Request req = new;
-  http:Response|false|error|() result = validateRequestHeader(createContext("get", "/test"), req, "testHeader", "test");
-
-
-  if !(result is http:Response) {
-    test:assertFail("Expected http:Response, found " + (typeof result).toString());
-  }
-
-
-  test:assertEquals(result.statusCode, http:STATUS_BAD_REQUEST, "Status code mismatch");
-}
-
-
-function createContext(string httpMethod, string resPath) returns mediation:Context {
-   mediation:ResourcePath originalPath = checkpanic mediation:createImmutableResourcePath(resPath);
-   mediation:Context originalCtx =
-               mediation:createImmutableMediationContext(httpMethod, originalPath.pathSegments(), {}, {});
-   mediation:ResourcePath mutableResPath = checkpanic mediation:createMutableResourcePath(resPath);
-   return mediation:createMutableMediationContext(originalCtx, mutableResPath.pathSegments(), {}, {});
-}
-
- -

The policy function modifies the same request/response/context instance that you pass to it. You can check the request/response/context instance after calling the policy function to verify changes.

-

Glossary

-

Here are some of the common terms used when working with policies in Choreo:

-

mediation:Context

-

The mediation context is used to pass parameters between policies. It is created per request and you can access it in any of the flows. For example, if a correlation ID needs to be set to the request, you can set it in the context of the request flow and access it in the response or fault flow.

-

The mediation context can include the following functions:

-
# Retrieves the value for the specified key.   
-public function get(string name) returns anydata;
-
-
-# Stores the provided key-value pair. If a mapping exists for the key, the value is overwritten.
-public function put(string name, anydata value);
-
-
-# Removes the entry mapped by the specified key and returns the removed value.
-public function remove(string name) returns anydata;
-
-
-# Retrieves the value for the specified key. If there is no mapping for the key, return the specified
-public function getOrDefault(string name, anydata default) returns anydata;
-
-
-# Checks whether a mapping exists for the specified key.
-public function hasKey(string name) returns boolean;
-
-
-# Returns the `mediation:Context` instance which captured the initial contextual information of the resource,
-# before the mediation flow was invoked. Calling this on an original `mediation:Context` object will return itself.
-public function originalContext() returns Context;
-
-
-# The HTTP method of the resource method
-public function httpMethod() returns string;
-
-
-# Retrieves an instance of `mediation:ResourcePath` which is an API for contextual information on the resource path
-# of this resource. It also contains methods for modifying the resource path as the user sees fit. This resource
-# path is the same path used by the mediation service for deriving the backend endpoint's resource to invoke.
-# Therefore, the default behavior of the mediation service is to invoke a resource in the backend endpoint which
-# has the same relative resource path as the corresponding mediation service resource.
-public function resourcePath() returns ResourcePath;
-
-
-# Sets the given `mediation:ResourcePath` instance as the resource path of this context.
-public function setResourcePath(ResourcePath path);
-
-
-# Adds a mapping between a path param name and a resolved value for it. There need not be a path parameter in the
-# resource path by the name specified in `name` for one to use this method. On its own, the path param values have
-# no bearing on the resource path.
-public function addPathParamValue(string name, PathParamValue value);
-
-
-# Returns the collection of resolved values for the path parameters in this particular context, mapped
-# by the parameter name.
-public function resolvedPathParams() returns map<PathParamValue> & readonly;
-
-
-# Removes the resolved path parameter value which maps to the specified name.
-public function removePathParamValue(string name);
-
-
-# Adds a query parameter to the request to be sent to the backend. If there is already a query parameter by
-# with the same name, the new value will be appended to it, making it an array.
-public function addQueryParam(string name, string value);
-
-
-# Removes the specified query parameter from the request. If the value of the parameter is an array, the whole
-# array will be removed.
-public function removeQueryParam(string name);
-
-
-# Retrieves a map of all the query parameters in the current request context. The returned map is a read-only snapshot
-# of the map of query parameters in the context at the time this method was called.
-public function queryParams() returns map<string[]> & readonly;
-
- -

Keywords

-

The Ballerina.toml file needs to include the following keywords for the mediation policies to work:

-
    -
  • choreo-apim-mediation-policy: This keyword is a mandatory keyword that is required to identify that the package is a mediation policy type.
    • -
  • choreo-apim-mediation-request-flow: Specifies whether the policy applies to the request flow.
    • -
  • choreo-apim-mediation-response-flow: Specifies whether the policy applies to the response flow.
    • -
  • choreo-apim-mediation-fault-flow: Specifies whether the policy is applicable for the fault flow.
    • -
-

Policy name and description

-

The Package.md file contains information about the policy. Choreo uses this information to render the policy configuring UI. This file is written in Markdown format and should be structured as follows.

-

Format:

-
# <policy-name>
-
-
-## Overview
-
-
-<policy description>
-
- -

Example:

-
# ValidateHeader
-
-
-## Overview
-
-
-This policy validates the request and response headers with the configured values.
-
- -

Policy versioning

-

When it comes to policy versioning in Choreo or mediation dependencies, it is important to consider the major version changes in the Ballerina language. For example, transitioning from update 1 to update 2 requires a major version increment, which can introduce significant incompatibilities.

-

Therefore, to ensure compatibility, the recommended approach is to version the policy package in a manner that the major version gets upgraded when the Choreo/mediation dependency version is upgraded to a major version.

- - - - - - -
-
- - -
- - - -
- - -
- - - -
-
-
- - - - - - - - - - - - - - - - - \ No newline at end of file diff --git a/en/site/api-management/api-rate-limiting/index.html b/en/site/api-management/api-rate-limiting/index.html deleted file mode 100644 index c0c8e3238..000000000 --- a/en/site/api-management/api-rate-limiting/index.html +++ /dev/null @@ -1,3239 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - API Rate Limiting - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- - - -
- - - - - - -
- - -
- -
- - - - - - - -
-
- - - -
-
-
- - - - -
-
-
- - - -
-
-
- - - -
-
-
- - - -
-
- - - - - - - - - - - - - - - - - - - - -

API Rate Limiting

-

API rate limiting is a technique that allows you to control the rate of requests made to an API. Rate limiting helps -prevent system overload and enhances API performance. When you limit the number of requests that can be made in a -specific time frame, you can ensure that your API is available and responsive to all users while protecting it from -malicious attacks.

-

This page walks you through the steps to enable rate limiting for your APIs via Choreo and also provides information on -the rate-limiting options supported by Choreo.

-

Enable rate limiting for an API

-

To enable rate limiting for an API, follow the steps given below:

-
-

Note

-

You can apply rate-limiting settings separately for each environment.

-
-
    -
  1. Sign in to the Choreo Console.
    2. -
  2. In the Component Listing pane, click on the component for which you want to apply rate limiting.
    3. -
  3. In the left navigation menu, click Deploy.
    4. -
  4. -

    Go to the required environment card and click the view icon corresponding to the endpoint for which you want to apply rate limiting.

    -
    -

    Info

    -

    If you are applying rate limiting for an API Proxy component, go to the required environment card, click the setting icon corresponding to API Configuration, and proceed to step 6.

    -
    -
    5. -
  5. -

    In the Endpoint Details pane that opens, click the settings icon.

    -
    6. -
  6. In the Manage section, click Rate Limiting to expand it.
    7. -
  7. Select a Rate Limiting Level depending on your requirement and click Apply.
    8. -
-

API-level rate limiting

-

API-level rate limiting applies the allocated request count for the specified time unit to all operations in the API.

-

Operation-level rate limiting

-

Operation-level rate limiting allows you to configure different rate-limiting values for each operation. You can use this option to define specific rate-limiting values for critical API operations that require an extra layer of protection.

-

Rate-limiting response headers

-

The following table lists the response headers available when you enable rate limiting for your APIs. You can implement necessary rate-limiting scenarios depending on the response header values.

- - - - - - - - - - - - - - - - - - - - - - - - - -
Header NameDescription
x-ratelimit-limitDenotes the request count allocated for the specified time unit.
x-ratelimit-resetProvides the time remaining to start the next rate-limiting time unit.
x-ratelimit-remainingDenotes the remaining request count for the specified time unit.
x-ratelimit-enforcedVisible after exceeding the allocated request count.
- - - - - - -
-
- - -
- - - -
- - -
- - - -
-
-
- - - - - - - - - - - - - - - - - \ No newline at end of file diff --git a/en/site/api-management/control-api-visibility/index.html b/en/site/api-management/control-api-visibility/index.html deleted file mode 100644 index b42207356..000000000 --- a/en/site/api-management/control-api-visibility/index.html +++ /dev/null @@ -1,3178 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - Control API Visibility - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- - - -
- - - - - - -
- - -
- -
- - - - - - - -
-
- - - -
-
-
- - - - -
-
-
- - - -
-
-
- - - -
-
-
- - - -
-
- - - - - - - - - - - - - - - - - - - - -

Control API Visibility

-

By default, the APIs published in Choreo are visible to anyone who visits the Choreo Developer Portal. By default, Choreo sets the visibility of the API to Public. However, developers can control the visibility of their APIs by changing the default option to Private or Restricted.

-

Visibility settings control users from viewing and modifying APIs. API visibility can be one of the following options:

-
    -
  • -

    Public : The API is visible to all in the developer portal.

    -
    • -
  • -

    Private : The API is visible to the users who only sign in to the Developer Portal.

    -
    • -
  • -

    Restricted: The API is visible to only the user that has the roles that you specify. This option helps developers to enforce fine-grained access control to the API.

    -
    • -
-

Change API visibility

-
    -
  1. Sign in to the Choreo Console.
    2. -
  2. In the Component Listing pane, click on the REST API (Service) for which you want to control API visibility.
    3. -
  3. In the left navigation menu, click Manage and then click API Info.
    4. -
  4. On the API Info page that opens, click the Developer Portal tab.
    5. -
  5. -

    Under General Details, select the required visibility setting from the Visibility list.

    -
    -

    Enable fine-grained role-based access control to the API

    -
      -
    1. To enable fine-grained role-based access control to an API in the Developer Portal, select Restricted from the API visibility list. Once selected, you will see the roles available in your organization in the Visible Roles list.
      2. -
    2. Select any combination of roles. Only the users with the given roles can access the APIs through the Dev Portal.
      3. -
    3. Alternatively, You can create a new role and assign it to an API by following the steps below:
        -
      1. Click + Create New Role in the list.
        2. -
      2. Add the role name and description.
        3. -
      3. Click Next.
        4. -
      4. Assign the relevant permissions to the new role.
        5. -
      5. Click Create.
        6. -
      6. Select the newly created role from the Visible Roles list.
        7. -
      -
      4. -
    -
    -
    6. -
  6. -

    Click Save.

    -
    7. -
- - - - - - -
-
- - -
- - - -
- - -
- - - -
-
-
- - - - - - - - - - - - - - - - - \ No newline at end of file diff --git a/en/site/api-management/documents/index.html b/en/site/api-management/documents/index.html deleted file mode 100644 index 36ae70d95..000000000 --- a/en/site/api-management/documents/index.html +++ /dev/null @@ -1,3165 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - Documents - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- - - -
- - - - - - -
- - -
- -
- - - - - - - -
-
- - - -
-
-
- - - - -
-
-
- - - -
-
-
- - - -
-
-
- - - -
-
- - - - - - - - - - - - - - - - - - - - -

Documents

-

When an API consumer signs in to the Choreo Developer Portal to browse APIs, it is not sufficient to just have an API thumbnail along with the name and version of the API. An API consumer would expect to see more details about the API, such as the following:

-
    -
  • A brief description of the API.
    • -
  • How to invoke the API.
    • -
  • The limitations/restrictions of the API.
    • -
  • Version history.
    • -
-

To provide such information that improves the overall visibility of the API, an API developer can add such documentation to an API before publishing it to the Developer Portal.

-

Add documents to an API

-

To add documentation for an API, follow the steps given below.

-
    -
  1. -

    Sign in to the Choreo Console.

    -
    2. -
  2. -

    In the Component Listing pane, click on the component for which you want to add documents.

    -
    3. -
  3. -

    In the left navigation menu, click Manage and then click Documents.

    -
    4. -
  4. -

    Specify a title for the document and provide the content in markdown syntax.

    -
    5. -
  5. -

    Click Add to save the document.

    -
    6. -
-

Depending on the information you need to add to the API, you can add one or more documents.

-

You can also edit existing documents and delete documents if necessary.

- - - - - - -
-
- - -
- - - -
- - -
- - - -
-
-
- - - - - - - - - - - - - - - - - \ No newline at end of file diff --git a/en/site/api-management/lifecycle-management/index.html b/en/site/api-management/lifecycle-management/index.html deleted file mode 100644 index c01411d01..000000000 --- a/en/site/api-management/lifecycle-management/index.html +++ /dev/null @@ -1,3207 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - Lifecycle Management - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- - - -
- - - - - - -
- - -
- -
- - - - - - - -
-
- - - -
-
-
- - - - -
-
-
- - - -
-
-
- - - -
-
-
- - - -
-
- - - - - - - - - - - - - - - - - - - - -

Lifecycle Management

-

API lifecycle management is an important aspect of API management. The API lifecycle consists of various states that an API passes through, from creation to retirement. In Choreo, there are six distinct lifecycle states: created, pre-released, published, blocked, deprecated, and retired.

-

By leveraging the various lifecycle states, API managers can optimize the development process and ensure that subscribers have access to the latest and most reliable APIs.

-

API lifecycle states

-

The following lifecycle states are applicable to APIs in Choreo:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
API lifecycle stateUse caseCorresponding action
CREATEDThe API is created but is not ready for consumption.The API is not visible to subscribers in the Developer Portal.
PRE-RELEASEDA prototype is created for early promotion and consumer testing. You can deploy a new API or a new version of an existing API as a prototype to provide subscribers with an early implementation of the API.The API is published to the Developer Portal as a pre-release.
PUBLISHEDThe API is ready for subscribers to view and subscribe to via the Developer PortalThe API is visible in the Developer Portal and is available for subscription.
BLOCKEDAccess to the API is temporarily blocked.Runtime calls are blocked, and the API is not visible in the Developer Portal.
DEPRECATEDThe old version of an API is moved to this state when a newer version of the API is PUBLISHED.The API is deployed and is available to existing subscribers. New subscriptions are disabled. Existing subscribers can continue to use it as usual until the API is retired.
RETIREDThe API is no longer in use when it is in this state.The API is unpublished and deleted from the Developer Portal.
-

Manage the lifecycle of an API

-

To change the lifecycle state of an API via the Choreo Console, follow the instructions given below:

-
-

Tip

-

You must have publishing privileges to manage the lifecycle states of a component.

-
-
    -
  1. Sign in to the Choreo Console.
    2. -
  2. In the Component Listing pane, click on the component for which you want to manage the lifecycle.
    3. -
  3. In the left navigation menu, click Manage, and then click Lifecycle.
    4. -
  4. In the Lifecycle Management pane, you will see the lifecycle state transition diagram indicating the current lifecycle state of the component. Just above the lifecycle state transition diagram, The possible lifecycle states you can apply to the component are displayed just above the lifecycle state transition diagram. Click on a required lifecycle state to apply it to the component. For example, if a component is in the Created state, you can click either Pre-release or Publish.
    5. -
- - - - - - -
-
- - -
- - - -
- - -
- - - -
-
-
- - - - - - - - - - - - - - - - - \ No newline at end of file diff --git a/en/site/api-management/manage-api-traffic/assign-subscription-plans-to-apis/index.html b/en/site/api-management/manage-api-traffic/assign-subscription-plans-to-apis/index.html deleted file mode 100644 index 93d492c3b..000000000 --- a/en/site/api-management/manage-api-traffic/assign-subscription-plans-to-apis/index.html +++ /dev/null @@ -1,3107 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - Assign Subscription Plans to APIs - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- - - -
- - - - - - -
- - -
- -
- - - - - - - -
-
- - - -
-
-
- - - - -
-
-
- - - -
-
-
- - - -
-
-
- - - -
-
- - - - - - - - - - - - - - - - - - - - -

Assign Subscription Plans to APIs

-

API subscription plans allow API publishers to control and manage access to APIs. These plans define the rules and limitations on how clients can interact with APIs, ensuring efficient resource utilization and robust security.

-

Choreo allows users with the administrator role to create, update, and delete subscription plans at the organization level. For instructions on creating subscription plans, see Create API Subscription Plans.

-

Once created, Choreo allows API publishers to assign subscription plans to APIs, providing different levels of access based on user needs.

-

To assign subscription plans to an API, follow the steps given below:

-
    -
  1. Sign in to the Choreo Console.
    2. -
  2. In the Component Listing pane, click on the component for which you want to assign subscription plans.
    3. -
  3. In the left navigation menu, click Manage and then click Subscription Plans. This displays the subscription plans available for the component.
    4. -
  4. -

    Enable the Subscription Plan Status toggle corresponding to the subscription plans you want to assign to the API.

    -

    Enable toggle

    -
    5. -
  5. -

    Click Save.

    -
    6. -
-

When an API has subscription plans assigned to it, API consumers can select the plan that best fits their requirements during the subscription process. For details, see Subscribe to an API with a Subscription Plan

- - - - - - -
-
- - -
- - - -
- - -
- - - -
-
-
- - - - - - - - - - - - - - - - - \ No newline at end of file diff --git a/en/site/api-management/manage-api-traffic/subscribe-to-an-api-with-a-subscription-plan/index.html b/en/site/api-management/manage-api-traffic/subscribe-to-an-api-with-a-subscription-plan/index.html deleted file mode 100644 index 5fe81fda8..000000000 --- a/en/site/api-management/manage-api-traffic/subscribe-to-an-api-with-a-subscription-plan/index.html +++ /dev/null @@ -1,3113 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - Subscribe to an API with a Subscription Plan - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- - - -
- - - - - - -
- - -
- -
- - - - - - - -
-
- - - -
-
-
- - - - -
-
-
- - - -
-
-
- - - -
-
-
- - - -
-
- - - - - - - - - - - - - - - - - - - - -

Subscribe to an API with a Subscription Plan

-

If an API has subscription plans assigned to it, API consumer can select the subscription plan that best fits their requirement at the time of subscribing to the API.

-

To subscribe to an API with a subscription plan, follow the steps given below:

-
    -
  1. Sign in to the Choreo Developer Portal.
    2. -
  2. In the Developer Portal header, click Applications.
    3. -
  3. On the My Applications page, click on the application you want to use to subscribe to an API.
    4. -
  4. In the left navigation menu, click Subscriptions.
    5. -
  5. In the Subscription Management pane that opens, click + Add APIs.
    6. -
  6. In the Add APIs pane that opens, select the API, API version, and subscription plan with which you want to subscribe to the API.
    7. -
  7. -

    Click Add Subscription.

    -

    Add subscription

    -
    8. -
-

To verify that the subscription plan works as expected, follow the steps given below:

-
    -
  1. In the Developer Portal header, click APIs.
    2. -
  2. Search for the API you subscribed to and click Try Out.
    3. -
  3. -

    Invoke the API until you exceed the request limit set in the subscription plan. You will see that the API throttles further requests once the limit is reached.

    -

    Throttle response

    -
    4. -
- - - - - - -
-
- - -
- - - -
- - -
- - - -
-
-
- - - - - - - - - - - - - - - - - \ No newline at end of file diff --git a/en/site/api-management/rename-api-display-name/index.html b/en/site/api-management/rename-api-display-name/index.html deleted file mode 100644 index 59f19eeb7..000000000 --- a/en/site/api-management/rename-api-display-name/index.html +++ /dev/null @@ -1,3102 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - Rename API Display Name - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- - - -
- - - - - - -
- - -
- -
- - - - - - - -
-
- - - -
-
-
- - - - -
-
-
- - - -
-
-
- - - -
-
-
- - - -
-
- - - - - - - - - - - - - - - - - - - - -

Rename API Display Name

-

Choreo allows you to make one or more endpoints accessible through its service and integration components. These endpoints are published as individual APIs in Choreo, accessible via the Choreo Developer Portal. By default, Choreo assigns an API name by combining the component name and the endpoint name, resulting in the following format: <component name>-<endpoint name>. For example, if you create a component named Ballerina Reading List, the API is displayed as Ballerina Reading List - GraphQL Reading List 591.

-

Choreo provides you with the flexibility to personalize the display name of the API, enhancing its user-friendliness and readability. Once you modify the API display name within the Choreo Console, Choreo applies the change immediately. From there onwards, Choreo displays the published API by this name in the Choreo Developer Portal.

-

Follow the steps below to rename the API display name:

-
    -
  1. Go to https://console.choreo.dev/ and sign in. This opens the project home page.
    2. -
  2. In the Component Listing pane, click on the component for which you want to rename the API display name. This opens the Overview page of the component.
    3. -
  3. In the left navigation menu, click Manage and then click API Info.
    4. -
  4. On the API Info page that opens, click the Developer Portal tab.
    5. -
  5. Under General Details, specify an appropriate API display name in the Name field.
    6. -
  6. Click Save.
    7. -
-

Now, you can view the updated API display name in the Choreo Developer Portal.

- - - - - - -
-
- - -
- - - -
- - -
- - - -
-
-
- - - - - - - - - - - - - - - - - \ No newline at end of file diff --git a/en/site/api-proxies/api-proxy/index.html b/en/site/api-proxies/api-proxy/index.html deleted file mode 100644 index d70b9ed94..000000000 --- a/en/site/api-proxies/api-proxy/index.html +++ /dev/null @@ -1,15 +0,0 @@ - - - - - - Redirecting... - - - - - - -Redirecting... - - diff --git a/en/site/api-proxies/index.html b/en/site/api-proxies/index.html deleted file mode 100644 index d70b9ed94..000000000 --- a/en/site/api-proxies/index.html +++ /dev/null @@ -1,15 +0,0 @@ - - - - - - Redirecting... - - - - - - -Redirecting... - - diff --git a/en/site/assets/images/favicon.png b/en/site/assets/images/favicon.png deleted file mode 100644 index 8e5c4ffeb..000000000 Binary files a/en/site/assets/images/favicon.png and /dev/null differ diff --git a/en/site/assets/images/logo.png b/en/site/assets/images/logo.png deleted file mode 100644 index 3f9c568b8..000000000 Binary files a/en/site/assets/images/logo.png and /dev/null differ diff --git a/en/site/assets/img/administer/configure-domain/active-domains.png b/en/site/assets/img/administer/configure-domain/active-domains.png deleted file mode 100644 index bbe5c9658..000000000 Binary files a/en/site/assets/img/administer/configure-domain/active-domains.png and /dev/null differ diff --git a/en/site/assets/img/administer/configure-domain/custom-url.png b/en/site/assets/img/administer/configure-domain/custom-url.png deleted file mode 100644 index 88bb1ab6b..000000000 Binary files a/en/site/assets/img/administer/configure-domain/custom-url.png and /dev/null differ diff --git a/en/site/assets/img/administer/configure-domain/pending-url-requests.png b/en/site/assets/img/administer/configure-domain/pending-url-requests.png deleted file mode 100644 index 625ceeb60..000000000 Binary files a/en/site/assets/img/administer/configure-domain/pending-url-requests.png and /dev/null differ diff --git a/en/site/assets/img/administer/create-subscription-plan.png b/en/site/assets/img/administer/create-subscription-plan.png deleted file mode 100644 index 7449bcea4..000000000 Binary files a/en/site/assets/img/administer/create-subscription-plan.png and /dev/null differ diff --git a/en/site/assets/img/administer/enterprise-login/group-mapping.png b/en/site/assets/img/administer/enterprise-login/group-mapping.png deleted file mode 100644 index 853a54fbc..000000000 Binary files a/en/site/assets/img/administer/enterprise-login/group-mapping.png and /dev/null differ diff --git a/en/site/assets/img/api-management/manage-api-traffic/enable-toggle.png b/en/site/assets/img/api-management/manage-api-traffic/enable-toggle.png deleted file mode 100644 index 5fbd0630f..000000000 Binary files a/en/site/assets/img/api-management/manage-api-traffic/enable-toggle.png and /dev/null differ diff --git a/en/site/assets/img/monitoring-and-insights/alerts/alert-configuration.png b/en/site/assets/img/monitoring-and-insights/alerts/alert-configuration.png deleted file mode 100644 index c7e5d1b02..000000000 Binary files a/en/site/assets/img/monitoring-and-insights/alerts/alert-configuration.png and /dev/null differ diff --git a/en/site/assets/img/monitoring-and-insights/engineering-insights/cio-dashboard.png b/en/site/assets/img/monitoring-and-insights/engineering-insights/cio-dashboard.png deleted file mode 100644 index 50a5ac8f7..000000000 Binary files a/en/site/assets/img/monitoring-and-insights/engineering-insights/cio-dashboard.png and /dev/null differ diff --git a/en/site/assets/img/monitoring-and-insights/engineering-insights/edit-configurations.png b/en/site/assets/img/monitoring-and-insights/engineering-insights/edit-configurations.png deleted file mode 100644 index d51c4cc69..000000000 Binary files a/en/site/assets/img/monitoring-and-insights/engineering-insights/edit-configurations.png and /dev/null differ diff --git a/en/site/assets/img/monitoring-and-insights/view-logs/audit-logs.png b/en/site/assets/img/monitoring-and-insights/view-logs/audit-logs.png deleted file mode 100644 index da5aa54b8..000000000 Binary files a/en/site/assets/img/monitoring-and-insights/view-logs/audit-logs.png and /dev/null differ diff --git a/en/site/assets/img/monitoring-and-insights/view-logs/create-role-to-view-audit-logs.png b/en/site/assets/img/monitoring-and-insights/view-logs/create-role-to-view-audit-logs.png deleted file mode 100644 index 7b76d00dd..000000000 Binary files a/en/site/assets/img/monitoring-and-insights/view-logs/create-role-to-view-audit-logs.png and /dev/null differ diff --git a/en/site/assets/img/monitoring-and-insights/view-logs/log-management-permission.png b/en/site/assets/img/monitoring-and-insights/view-logs/log-management-permission.png deleted file mode 100644 index bf4e86ba8..000000000 Binary files a/en/site/assets/img/monitoring-and-insights/view-logs/log-management-permission.png and /dev/null differ diff --git a/en/site/assets/img/monitoring-and-insights/view-logs/runtime-logs.png b/en/site/assets/img/monitoring-and-insights/view-logs/runtime-logs.png deleted file mode 100644 index 34bdedbe1..000000000 Binary files a/en/site/assets/img/monitoring-and-insights/view-logs/runtime-logs.png and /dev/null differ diff --git a/en/site/assets/javascripts/application.js b/en/site/assets/javascripts/application.js deleted file mode 100644 index 54acf4fe9..000000000 --- a/en/site/assets/javascripts/application.js +++ /dev/null @@ -1,410 +0,0 @@ -/* - * Copyright (c) 2016-2017 Martin Donath - * - * Permission is hereby granted, free of charge, to any person obtaining a copy - * of this software and associated documentation files (the "Software"), to - * deal in the Software without restriction, including without limitation the - * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or - * sell copies of the Software, and to permit persons to whom the Software is - * furnished to do so, subject to the following conditions: - * - * The above copyright notice and this permission notice shall be included in - * all copies or substantial portions of the Software. - * - * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR - * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, - * FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT. IN NO EVENT SHALL THE - * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER - * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING - * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS - * IN THE SOFTWARE. - */ - -import Clipboard from "clipboard" -import FastClick from "fastclick" - -import Material from "./components/Material" - -/* ---------------------------------------------------------------------------- - * Application - * ------------------------------------------------------------------------- */ - -/** - * Initialize Material for MkDocs - * - * @param {Object} config - Configuration - */ -function initialize(config) { // eslint-disable-line func-style - - /* Initialize Modernizr and FastClick */ - new Material.Event.Listener(document, "DOMContentLoaded", () => { - if (!(document.body instanceof HTMLElement)) - throw new ReferenceError - - /* Attach FastClick to mitigate 300ms delay on touch devices */ - FastClick.attach(document.body) - - /* Test for iOS */ - Modernizr.addTest("ios", () => { - return !!navigator.userAgent.match(/(iPad|iPhone|iPod)/g) - }) - - /* Wrap all data tables for better overflow scrolling */ - const tables = document.querySelectorAll("table:not([class])") // TODO: this is JSX, we should rename the file - Array.prototype.forEach.call(tables, table => { - const wrap = ( -
-
-
- ) - if (table.nextSibling) { - table.parentNode.insertBefore(wrap, table.nextSibling) - } else { - table.parentNode.appendChild(wrap) - } - wrap.children[0].appendChild(table) - }) - - /* Clipboard integration */ - if (Clipboard.isSupported()) { - const blocks = document.querySelectorAll("div > pre, pre > code") - Array.prototype.forEach.call(blocks, (block, index) => { - const id = `__code_${index}` - - /* Create button with message container */ - const button = ( - - ) - - /* Link to block and insert button */ - const parent = block.parentNode - parent.id = id - parent.insertBefore(button, block) - }) - - /* Initialize Clipboard listener */ - const copy = new Clipboard(".md-clipboard") - - /* Success handler */ - copy.on("success", action => { - const message = action.trigger.querySelector(".md-clipboard__message") - if (!(message instanceof HTMLElement)) - throw new ReferenceError - - /* Clear selection and reset debounce logic */ - action.clearSelection() - if (message.dataset.mdTimer) - clearTimeout(parseInt(message.dataset.mdTimer, 10)) - - /* Set message indicating success and show it */ - message.classList.add("md-clipboard__message--active") - message.innerHTML = "Copied to clipboard" - - /* Hide message after two seconds */ - message.dataset.mdTimer = setTimeout(() => { - message.classList.remove("md-clipboard__message--active") - message.dataset.mdTimer = "" - }, 2000).toString() - }) - } - - /* Polyfill details/summary functionality */ - if (!Modernizr.details) { - const blocks = document.querySelectorAll("details > summary") - Array.prototype.forEach.call(blocks, summary => { - summary.addEventListener("click", ev => { - const details = ev.target.parentNode - if (details.hasAttribute("open")) { - details.removeAttribute("open") - } else { - details.setAttribute("open", "") - } - }) - }) - } - - /* Force 1px scroll offset to trigger overflow scrolling */ - if (Modernizr.ios) { - const scrollable = document.querySelectorAll("[data-md-scrollfix]") - Array.prototype.forEach.call(scrollable, item => { - item.addEventListener("touchstart", () => { - const top = item.scrollTop - - /* We're at the top of the container */ - if (top === 0) { - item.scrollTop = 1 - - /* We're at the bottom of the container */ - } else if (top + item.offsetHeight === item.scrollHeight) { - item.scrollTop = top - 1 - } - }) - }) - } - }).listen() - - /* Component: header shadow toggle */ - new Material.Event.MatchMedia("(min-width: 1220px)", - new Material.Event.Listener(window, [ - "scroll", "resize", "orientationchange" - ], new Material.Header.Shadow( - "[data-md-component=container]", - "[data-md-component=header]"))) - - /* Component: tabs visibility toggle */ - if (document.querySelector("[data-md-component=tabs]")) - new Material.Event.Listener(window, [ - "scroll", "resize", "orientationchange" - ], new Material.Tabs.Toggle("[data-md-component=tabs]")).listen() - - /* Component: sidebar with navigation */ - new Material.Event.MatchMedia("(min-width: 1220px)", - new Material.Event.Listener(window, [ - "scroll", "resize", "orientationchange" - ], new Material.Sidebar.Position( - "[data-md-component=navigation]", - "[data-md-component=header]"))) - - /* Component: sidebar with table of contents (missing on 404 page) */ - if (document.querySelector("[data-md-component=toc]")) - new Material.Event.MatchMedia("(min-width: 960px)", - new Material.Event.Listener(window, [ - "scroll", "resize", "orientationchange" - ], new Material.Sidebar.Position( - "[data-md-component=toc]", - "[data-md-component=header]"))) - - /* Component: link blurring for table of contents */ - new Material.Event.MatchMedia("(min-width: 960px)", - new Material.Event.Listener(window, "scroll", - new Material.Nav.Blur("[data-md-component=toc] [href]"))) - - /* Component: collapsible elements for navigation */ - const collapsibles = - document.querySelectorAll("[data-md-component=collapsible]") - Array.prototype.forEach.call(collapsibles, collapse => { - new Material.Event.MatchMedia("(min-width: 1220px)", - new Material.Event.Listener(collapse.previousElementSibling, "click", - new Material.Nav.Collapse(collapse))) - }) - - /* Component: active pane monitor for iOS scrolling fixes */ - new Material.Event.MatchMedia("(max-width: 1219px)", - new Material.Event.Listener( - "[data-md-component=navigation] [data-md-toggle]", "change", - new Material.Nav.Scrolling("[data-md-component=navigation] nav"))) - - /* Component: search body lock for mobile */ - new Material.Event.MatchMedia("(max-width: 959px)", - new Material.Event.Listener("[data-md-toggle=search]", "change", - new Material.Search.Lock("[data-md-toggle=search]"))) - - /* Component: search results */ - new Material.Event.Listener("[data-md-component=query]", [ - "focus", "keyup", "change" - ], new Material.Search.Result("[data-md-component=result]", () => { - return fetch(`${config.url.base}/${ - config.version < "0.17" ? "mkdocs" : "search" - }/search_index.json`, { - credentials: "same-origin" - }).then(response => response.json()) - .then(data => { - return data.docs.map(doc => { - doc.location = config.url.base + doc.location - return doc - }) - }) - })).listen() - - /* Listener: close drawer when anchor links are clicked */ - new Material.Event.MatchMedia("(max-width: 959px)", - new Material.Event.Listener("[data-md-component=navigation] [href^='#']", - "click", () => { - const toggle = document.querySelector("[data-md-toggle=drawer]") - if (!(toggle instanceof HTMLInputElement)) - throw new ReferenceError - if (toggle.checked) { - toggle.checked = false - toggle.dispatchEvent(new CustomEvent("change")) - } - })) - - /* Listener: focus input after form reset */ - new Material.Event.Listener("[data-md-component=reset]", "click", () => { - setTimeout(() => { - const query = document.querySelector("[data-md-component=query]") - if (!(query instanceof HTMLInputElement)) - throw new ReferenceError - query.focus() - }, 10) - }).listen() - - /* Listener: focus input after opening search */ - new Material.Event.Listener("[data-md-toggle=search]", "change", ev => { - alert("change"); - setTimeout(toggle => { - if (!(toggle instanceof HTMLInputElement)) - throw new ReferenceError - if (toggle.checked) { - const query = document.querySelector("[data-md-component=query]") - if (!(query instanceof HTMLInputElement)) - throw new ReferenceError - query.focus() - } - }, 400, ev.target) - }).listen() - - /* Listener: open search on focus */ - new Material.Event.MatchMedia("(min-width: 960px)", - new Material.Event.Listener("[data-md-component=query]", "focus", () => { - const toggle = document.querySelector("[data-md-toggle=search]") - if (!(toggle instanceof HTMLInputElement)) - throw new ReferenceError - if (!toggle.checked) { - toggle.checked = true - toggle.dispatchEvent(new CustomEvent("change")) - } - })) - - /* Listener: keyboard handlers */ // eslint-disable-next-line complexity - new Material.Event.Listener(window, "keydown", ev => { - alert("found"); - // TODO: split up into component to reduce complexity - const toggle = document.querySelector("[data-md-toggle=search]") - if (!(toggle instanceof HTMLInputElement)) - throw new ReferenceError - const query = document.querySelector("[data-md-component=query]") - if (!(query instanceof HTMLInputElement)) - throw new ReferenceError - - /* Abort if meta key (macOS) or ctrl key (Windows) is pressed */ - if (ev.metaKey || ev.ctrlKey) - return - - /* Search is open */ - if (toggle.checked) { - - /* Enter: prevent form submission */ - if (ev.keyCode === 13) { - if (query === document.activeElement) { - ev.preventDefault() - - /* Go to current active/focused link */ - const focus = document.querySelector( - "[data-md-component=search] [href][data-md-state=active]") - if (focus instanceof HTMLLinkElement) { - window.location = focus.getAttribute("href") - - /* Close search */ - toggle.checked = false - toggle.dispatchEvent(new CustomEvent("change")) - query.blur() - } - } - - /* Escape: close search */ - } else if (ev.keyCode === 27) { - toggle.checked = false - toggle.dispatchEvent(new CustomEvent("change")) - query.blur() - - /* Horizontal arrows and backspace: focus input */ - } else if ([8, 37, 39].indexOf(ev.keyCode) !== -1) { - if (query !== document.activeElement) - query.focus() - - /* Vertical arrows and tab: select previous or next search result */ - } else if ([9, 38, 40].indexOf(ev.keyCode) !== -1) { - const map = ev.shiftKey ? 38 : 40 - const key = ev.keyCode === 9 ? map : ev.keyCode - - /* Retrieve all results */ - const links = Array.prototype.slice.call( - document.querySelectorAll( - "[data-md-component=query], [data-md-component=search] [href]")) - - /* Retrieve current active/focused result */ - const focus = links.find(link => { - if (!(link instanceof HTMLElement)) - throw new ReferenceError - return link.dataset.mdState === "active" - }) - if (focus) - focus.dataset.mdState = "" - - /* Calculate index depending on direction, add length to form ring */ - const index = Math.max(0, ( - links.indexOf(focus) + links.length + (key === 38 ? -1 : +1) - ) % links.length) - - /* Set active state and focus */ - if (links[index]) { - links[index].dataset.mdState = "active" - links[index].focus() - } - - /* Prevent scrolling of page */ - ev.preventDefault() - ev.stopPropagation() - - /* Return false prevents the cursor position from changing */ - return false - } - - /* Search is closed and we're not inside a form */ - } else if (document.activeElement && !document.activeElement.form) { - - /* F/S: Open search if not in input field */ - // if (ev.keyCode === 70 || ev.keyCode === 83) { - // query.focus() - // ev.preventDefault() - // } - } - }).listen() - - /* Listener: focus query if in search is open and character is typed */ - new Material.Event.Listener(window, "keypress", () => { - const toggle = document.querySelector("[data-md-toggle=search]") - if (!(toggle instanceof HTMLInputElement)) - throw new ReferenceError - if (toggle.checked) { - const query = document.querySelector("[data-md-component=query]") - if (!(query instanceof HTMLInputElement)) - throw new ReferenceError - if (query !== document.activeElement) - query.focus() - } - }).listen() - - /* Retrieve facts for the given repository type */ - ;(() => { - const el = document.querySelector("[data-md-source]") - if (!el) - return Promise.resolve([]) - else if (!(el instanceof HTMLAnchorElement)) - throw new ReferenceError - switch (el.dataset.mdSource) { - case "github": return new Material.Source.Adapter.GitHub(el).fetch() - default: return Promise.resolve([]) - } - - /* Render repository information */ - })().then(facts => { - const sources = document.querySelectorAll("[data-md-source]") - Array.prototype.forEach.call(sources, source => { - new Material.Source.Repository(source) - .initialize(facts) - }) - }) -} - -/* ---------------------------------------------------------------------------- - * Exports - * ------------------------------------------------------------------------- */ - -export { - initialize -} diff --git a/en/site/assets/javascripts/bundle.fc8c2696.min.js b/en/site/assets/javascripts/bundle.fc8c2696.min.js deleted file mode 100644 index 359c24cd8..000000000 --- a/en/site/assets/javascripts/bundle.fc8c2696.min.js +++ /dev/null @@ -1,29 +0,0 @@ -"use strict";(()=>{var Ri=Object.create;var gr=Object.defineProperty;var ki=Object.getOwnPropertyDescriptor;var Hi=Object.getOwnPropertyNames,kt=Object.getOwnPropertySymbols,Pi=Object.getPrototypeOf,yr=Object.prototype.hasOwnProperty,on=Object.prototype.propertyIsEnumerable;var nn=(e,t,r)=>t in e?gr(e,t,{enumerable:!0,configurable:!0,writable:!0,value:r}):e[t]=r,P=(e,t)=>{for(var r in t||(t={}))yr.call(t,r)&&nn(e,r,t[r]);if(kt)for(var r of kt(t))on.call(t,r)&&nn(e,r,t[r]);return e};var an=(e,t)=>{var r={};for(var n in e)yr.call(e,n)&&t.indexOf(n)<0&&(r[n]=e[n]);if(e!=null&&kt)for(var n of kt(e))t.indexOf(n)<0&&on.call(e,n)&&(r[n]=e[n]);return r};var Ht=(e,t)=>()=>(t||e((t={exports:{}}).exports,t),t.exports);var $i=(e,t,r,n)=>{if(t&&typeof t=="object"||typeof t=="function")for(let o of Hi(t))!yr.call(e,o)&&o!==r&&gr(e,o,{get:()=>t[o],enumerable:!(n=ki(t,o))||n.enumerable});return e};var yt=(e,t,r)=>(r=e!=null?Ri(Pi(e)):{},$i(t||!e||!e.__esModule?gr(r,"default",{value:e,enumerable:!0}):r,e));var cn=Ht((xr,sn)=>{(function(e,t){typeof xr=="object"&&typeof sn!="undefined"?t():typeof define=="function"&&define.amd?define(t):t()})(xr,function(){"use strict";function e(r){var n=!0,o=!1,i=null,s={text:!0,search:!0,url:!0,tel:!0,email:!0,password:!0,number:!0,date:!0,month:!0,week:!0,time:!0,datetime:!0,"datetime-local":!0};function a(T){return!!(T&&T!==document&&T.nodeName!=="HTML"&&T.nodeName!=="BODY"&&"classList"in T&&"contains"in T.classList)}function c(T){var Qe=T.type,De=T.tagName;return!!(De==="INPUT"&&s[Qe]&&!T.readOnly||De==="TEXTAREA"&&!T.readOnly||T.isContentEditable)}function f(T){T.classList.contains("focus-visible")||(T.classList.add("focus-visible"),T.setAttribute("data-focus-visible-added",""))}function u(T){T.hasAttribute("data-focus-visible-added")&&(T.classList.remove("focus-visible"),T.removeAttribute("data-focus-visible-added"))}function p(T){T.metaKey||T.altKey||T.ctrlKey||(a(r.activeElement)&&f(r.activeElement),n=!0)}function m(T){n=!1}function d(T){a(T.target)&&(n||c(T.target))&&f(T.target)}function h(T){a(T.target)&&(T.target.classList.contains("focus-visible")||T.target.hasAttribute("data-focus-visible-added"))&&(o=!0,window.clearTimeout(i),i=window.setTimeout(function(){o=!1},100),u(T.target))}function v(T){document.visibilityState==="hidden"&&(o&&(n=!0),G())}function G(){document.addEventListener("mousemove",N),document.addEventListener("mousedown",N),document.addEventListener("mouseup",N),document.addEventListener("pointermove",N),document.addEventListener("pointerdown",N),document.addEventListener("pointerup",N),document.addEventListener("touchmove",N),document.addEventListener("touchstart",N),document.addEventListener("touchend",N)}function oe(){document.removeEventListener("mousemove",N),document.removeEventListener("mousedown",N),document.removeEventListener("mouseup",N),document.removeEventListener("pointermove",N),document.removeEventListener("pointerdown",N),document.removeEventListener("pointerup",N),document.removeEventListener("touchmove",N),document.removeEventListener("touchstart",N),document.removeEventListener("touchend",N)}function N(T){T.target.nodeName&&T.target.nodeName.toLowerCase()==="html"||(n=!1,oe())}document.addEventListener("keydown",p,!0),document.addEventListener("mousedown",m,!0),document.addEventListener("pointerdown",m,!0),document.addEventListener("touchstart",m,!0),document.addEventListener("visibilitychange",v,!0),G(),r.addEventListener("focus",d,!0),r.addEventListener("blur",h,!0),r.nodeType===Node.DOCUMENT_FRAGMENT_NODE&&r.host?r.host.setAttribute("data-js-focus-visible",""):r.nodeType===Node.DOCUMENT_NODE&&(document.documentElement.classList.add("js-focus-visible"),document.documentElement.setAttribute("data-js-focus-visible",""))}if(typeof window!="undefined"&&typeof document!="undefined"){window.applyFocusVisiblePolyfill=e;var t;try{t=new CustomEvent("focus-visible-polyfill-ready")}catch(r){t=document.createEvent("CustomEvent"),t.initCustomEvent("focus-visible-polyfill-ready",!1,!1,{})}window.dispatchEvent(t)}typeof document!="undefined"&&e(document)})});var fn=Ht(Er=>{(function(e){var t=function(){try{return!!Symbol.iterator}catch(f){return!1}},r=t(),n=function(f){var u={next:function(){var p=f.shift();return{done:p===void 0,value:p}}};return r&&(u[Symbol.iterator]=function(){return u}),u},o=function(f){return encodeURIComponent(f).replace(/%20/g,"+")},i=function(f){return decodeURIComponent(String(f).replace(/\+/g," "))},s=function(){var f=function(p){Object.defineProperty(this,"_entries",{writable:!0,value:{}});var m=typeof p;if(m!=="undefined")if(m==="string")p!==""&&this._fromString(p);else if(p instanceof f){var d=this;p.forEach(function(oe,N){d.append(N,oe)})}else if(p!==null&&m==="object")if(Object.prototype.toString.call(p)==="[object Array]")for(var h=0;hd[0]?1:0}),f._entries&&(f._entries={});for(var p=0;p1?i(d[1]):"")}})})(typeof global!="undefined"?global:typeof window!="undefined"?window:typeof self!="undefined"?self:Er);(function(e){var t=function(){try{var o=new e.URL("b","http://a");return o.pathname="c d",o.href==="http://a/c%20d"&&o.searchParams}catch(i){return!1}},r=function(){var o=e.URL,i=function(c,f){typeof c!="string"&&(c=String(c)),f&&typeof f!="string"&&(f=String(f));var u=document,p;if(f&&(e.location===void 0||f!==e.location.href)){f=f.toLowerCase(),u=document.implementation.createHTMLDocument(""),p=u.createElement("base"),p.href=f,u.head.appendChild(p);try{if(p.href.indexOf(f)!==0)throw new Error(p.href)}catch(T){throw new Error("URL unable to set base "+f+" due to "+T)}}var m=u.createElement("a");m.href=c,p&&(u.body.appendChild(m),m.href=m.href);var d=u.createElement("input");if(d.type="url",d.value=c,m.protocol===":"||!/:/.test(m.href)||!d.checkValidity()&&!f)throw new TypeError("Invalid URL");Object.defineProperty(this,"_anchorElement",{value:m});var h=new e.URLSearchParams(this.search),v=!0,G=!0,oe=this;["append","delete","set"].forEach(function(T){var Qe=h[T];h[T]=function(){Qe.apply(h,arguments),v&&(G=!1,oe.search=h.toString(),G=!0)}}),Object.defineProperty(this,"searchParams",{value:h,enumerable:!0});var N=void 0;Object.defineProperty(this,"_updateSearchParams",{enumerable:!1,configurable:!1,writable:!1,value:function(){this.search!==N&&(N=this.search,G&&(v=!1,this.searchParams._fromString(this.search),v=!0))}})},s=i.prototype,a=function(c){Object.defineProperty(s,c,{get:function(){return this._anchorElement[c]},set:function(f){this._anchorElement[c]=f},enumerable:!0})};["hash","host","hostname","port","protocol"].forEach(function(c){a(c)}),Object.defineProperty(s,"search",{get:function(){return this._anchorElement.search},set:function(c){this._anchorElement.search=c,this._updateSearchParams()},enumerable:!0}),Object.defineProperties(s,{toString:{get:function(){var c=this;return function(){return c.href}}},href:{get:function(){return this._anchorElement.href.replace(/\?$/,"")},set:function(c){this._anchorElement.href=c,this._updateSearchParams()},enumerable:!0},pathname:{get:function(){return this._anchorElement.pathname.replace(/(^\/?)/,"/")},set:function(c){this._anchorElement.pathname=c},enumerable:!0},origin:{get:function(){var c={"http:":80,"https:":443,"ftp:":21}[this._anchorElement.protocol],f=this._anchorElement.port!=c&&this._anchorElement.port!=="";return this._anchorElement.protocol+"//"+this._anchorElement.hostname+(f?":"+this._anchorElement.port:"")},enumerable:!0},password:{get:function(){return""},set:function(c){},enumerable:!0},username:{get:function(){return""},set:function(c){},enumerable:!0}}),i.createObjectURL=function(c){return o.createObjectURL.apply(o,arguments)},i.revokeObjectURL=function(c){return o.revokeObjectURL.apply(o,arguments)},e.URL=i};if(t()||r(),e.location!==void 0&&!("origin"in e.location)){var n=function(){return e.location.protocol+"//"+e.location.hostname+(e.location.port?":"+e.location.port:"")};try{Object.defineProperty(e.location,"origin",{get:n,enumerable:!0})}catch(o){setInterval(function(){e.location.origin=n()},100)}}})(typeof global!="undefined"?global:typeof window!="undefined"?window:typeof self!="undefined"?self:Er)});var Kr=Ht((Mt,qr)=>{/*! - * clipboard.js v2.0.11 - * https://clipboardjs.com/ - * - * Licensed MIT © Zeno Rocha - */(function(t,r){typeof Mt=="object"&&typeof qr=="object"?qr.exports=r():typeof define=="function"&&define.amd?define([],r):typeof Mt=="object"?Mt.ClipboardJS=r():t.ClipboardJS=r()})(Mt,function(){return function(){var e={686:function(n,o,i){"use strict";i.d(o,{default:function(){return Ci}});var s=i(279),a=i.n(s),c=i(370),f=i.n(c),u=i(817),p=i.n(u);function m(j){try{return document.execCommand(j)}catch(O){return!1}}var d=function(O){var E=p()(O);return m("cut"),E},h=d;function v(j){var O=document.documentElement.getAttribute("dir")==="rtl",E=document.createElement("textarea");E.style.fontSize="12pt",E.style.border="0",E.style.padding="0",E.style.margin="0",E.style.position="absolute",E.style[O?"right":"left"]="-9999px";var H=window.pageYOffset||document.documentElement.scrollTop;return E.style.top="".concat(H,"px"),E.setAttribute("readonly",""),E.value=j,E}var G=function(O,E){var H=v(O);E.container.appendChild(H);var I=p()(H);return m("copy"),H.remove(),I},oe=function(O){var E=arguments.length>1&&arguments[1]!==void 0?arguments[1]:{container:document.body},H="";return typeof O=="string"?H=G(O,E):O instanceof HTMLInputElement&&!["text","search","url","tel","password"].includes(O==null?void 0:O.type)?H=G(O.value,E):(H=p()(O),m("copy")),H},N=oe;function T(j){return typeof Symbol=="function"&&typeof Symbol.iterator=="symbol"?T=function(E){return typeof E}:T=function(E){return E&&typeof Symbol=="function"&&E.constructor===Symbol&&E!==Symbol.prototype?"symbol":typeof E},T(j)}var Qe=function(){var O=arguments.length>0&&arguments[0]!==void 0?arguments[0]:{},E=O.action,H=E===void 0?"copy":E,I=O.container,q=O.target,Me=O.text;if(H!=="copy"&&H!=="cut")throw new Error('Invalid "action" value, use either "copy" or "cut"');if(q!==void 0)if(q&&T(q)==="object"&&q.nodeType===1){if(H==="copy"&&q.hasAttribute("disabled"))throw new Error('Invalid "target" attribute. Please use "readonly" instead of "disabled" attribute');if(H==="cut"&&(q.hasAttribute("readonly")||q.hasAttribute("disabled")))throw new Error(`Invalid "target" attribute. You can't cut text from elements with "readonly" or "disabled" attributes`)}else throw new Error('Invalid "target" value, use a valid Element');if(Me)return N(Me,{container:I});if(q)return H==="cut"?h(q):N(q,{container:I})},De=Qe;function $e(j){return typeof Symbol=="function"&&typeof Symbol.iterator=="symbol"?$e=function(E){return typeof E}:$e=function(E){return E&&typeof Symbol=="function"&&E.constructor===Symbol&&E!==Symbol.prototype?"symbol":typeof E},$e(j)}function wi(j,O){if(!(j instanceof O))throw new TypeError("Cannot call a class as a function")}function rn(j,O){for(var E=0;E0&&arguments[0]!==void 0?arguments[0]:{};this.action=typeof I.action=="function"?I.action:this.defaultAction,this.target=typeof I.target=="function"?I.target:this.defaultTarget,this.text=typeof I.text=="function"?I.text:this.defaultText,this.container=$e(I.container)==="object"?I.container:document.body}},{key:"listenClick",value:function(I){var q=this;this.listener=f()(I,"click",function(Me){return q.onClick(Me)})}},{key:"onClick",value:function(I){var q=I.delegateTarget||I.currentTarget,Me=this.action(q)||"copy",Rt=De({action:Me,container:this.container,target:this.target(q),text:this.text(q)});this.emit(Rt?"success":"error",{action:Me,text:Rt,trigger:q,clearSelection:function(){q&&q.focus(),window.getSelection().removeAllRanges()}})}},{key:"defaultAction",value:function(I){return vr("action",I)}},{key:"defaultTarget",value:function(I){var q=vr("target",I);if(q)return document.querySelector(q)}},{key:"defaultText",value:function(I){return vr("text",I)}},{key:"destroy",value:function(){this.listener.destroy()}}],[{key:"copy",value:function(I){var q=arguments.length>1&&arguments[1]!==void 0?arguments[1]:{container:document.body};return N(I,q)}},{key:"cut",value:function(I){return h(I)}},{key:"isSupported",value:function(){var I=arguments.length>0&&arguments[0]!==void 0?arguments[0]:["copy","cut"],q=typeof I=="string"?[I]:I,Me=!!document.queryCommandSupported;return q.forEach(function(Rt){Me=Me&&!!document.queryCommandSupported(Rt)}),Me}}]),E}(a()),Ci=Ai},828:function(n){var o=9;if(typeof Element!="undefined"&&!Element.prototype.matches){var i=Element.prototype;i.matches=i.matchesSelector||i.mozMatchesSelector||i.msMatchesSelector||i.oMatchesSelector||i.webkitMatchesSelector}function s(a,c){for(;a&&a.nodeType!==o;){if(typeof a.matches=="function"&&a.matches(c))return a;a=a.parentNode}}n.exports=s},438:function(n,o,i){var s=i(828);function a(u,p,m,d,h){var v=f.apply(this,arguments);return u.addEventListener(m,v,h),{destroy:function(){u.removeEventListener(m,v,h)}}}function c(u,p,m,d,h){return typeof u.addEventListener=="function"?a.apply(null,arguments):typeof m=="function"?a.bind(null,document).apply(null,arguments):(typeof u=="string"&&(u=document.querySelectorAll(u)),Array.prototype.map.call(u,function(v){return a(v,p,m,d,h)}))}function f(u,p,m,d){return function(h){h.delegateTarget=s(h.target,p),h.delegateTarget&&d.call(u,h)}}n.exports=c},879:function(n,o){o.node=function(i){return i!==void 0&&i instanceof HTMLElement&&i.nodeType===1},o.nodeList=function(i){var s=Object.prototype.toString.call(i);return i!==void 0&&(s==="[object NodeList]"||s==="[object HTMLCollection]")&&"length"in i&&(i.length===0||o.node(i[0]))},o.string=function(i){return typeof i=="string"||i instanceof String},o.fn=function(i){var s=Object.prototype.toString.call(i);return s==="[object Function]"}},370:function(n,o,i){var s=i(879),a=i(438);function c(m,d,h){if(!m&&!d&&!h)throw new Error("Missing required arguments");if(!s.string(d))throw new TypeError("Second argument must be a String");if(!s.fn(h))throw new TypeError("Third argument must be a Function");if(s.node(m))return f(m,d,h);if(s.nodeList(m))return u(m,d,h);if(s.string(m))return p(m,d,h);throw new TypeError("First argument must be a String, HTMLElement, HTMLCollection, or NodeList")}function f(m,d,h){return m.addEventListener(d,h),{destroy:function(){m.removeEventListener(d,h)}}}function u(m,d,h){return Array.prototype.forEach.call(m,function(v){v.addEventListener(d,h)}),{destroy:function(){Array.prototype.forEach.call(m,function(v){v.removeEventListener(d,h)})}}}function p(m,d,h){return a(document.body,m,d,h)}n.exports=c},817:function(n){function o(i){var s;if(i.nodeName==="SELECT")i.focus(),s=i.value;else if(i.nodeName==="INPUT"||i.nodeName==="TEXTAREA"){var a=i.hasAttribute("readonly");a||i.setAttribute("readonly",""),i.select(),i.setSelectionRange(0,i.value.length),a||i.removeAttribute("readonly"),s=i.value}else{i.hasAttribute("contenteditable")&&i.focus();var c=window.getSelection(),f=document.createRange();f.selectNodeContents(i),c.removeAllRanges(),c.addRange(f),s=c.toString()}return s}n.exports=o},279:function(n){function o(){}o.prototype={on:function(i,s,a){var c=this.e||(this.e={});return(c[i]||(c[i]=[])).push({fn:s,ctx:a}),this},once:function(i,s,a){var c=this;function f(){c.off(i,f),s.apply(a,arguments)}return f._=s,this.on(i,f,a)},emit:function(i){var s=[].slice.call(arguments,1),a=((this.e||(this.e={}))[i]||[]).slice(),c=0,f=a.length;for(c;c{"use strict";/*! - * escape-html - * Copyright(c) 2012-2013 TJ Holowaychuk - * Copyright(c) 2015 Andreas Lubbe - * Copyright(c) 2015 Tiancheng "Timothy" Gu - * MIT Licensed - */var ns=/["'&<>]/;Go.exports=os;function os(e){var t=""+e,r=ns.exec(t);if(!r)return t;var n,o="",i=0,s=0;for(i=r.index;i0&&i[i.length-1])&&(f[0]===6||f[0]===2)){r=0;continue}if(f[0]===3&&(!i||f[1]>i[0]&&f[1]=e.length&&(e=void 0),{value:e&&e[n++],done:!e}}};throw new TypeError(t?"Object is not iterable.":"Symbol.iterator is not defined.")}function W(e,t){var r=typeof Symbol=="function"&&e[Symbol.iterator];if(!r)return e;var n=r.call(e),o,i=[],s;try{for(;(t===void 0||t-- >0)&&!(o=n.next()).done;)i.push(o.value)}catch(a){s={error:a}}finally{try{o&&!o.done&&(r=n.return)&&r.call(n)}finally{if(s)throw s.error}}return i}function D(e,t,r){if(r||arguments.length===2)for(var n=0,o=t.length,i;n1||a(m,d)})})}function a(m,d){try{c(n[m](d))}catch(h){p(i[0][3],h)}}function c(m){m.value instanceof et?Promise.resolve(m.value.v).then(f,u):p(i[0][2],m)}function f(m){a("next",m)}function u(m){a("throw",m)}function p(m,d){m(d),i.shift(),i.length&&a(i[0][0],i[0][1])}}function ln(e){if(!Symbol.asyncIterator)throw new TypeError("Symbol.asyncIterator is not defined.");var t=e[Symbol.asyncIterator],r;return t?t.call(e):(e=typeof Ee=="function"?Ee(e):e[Symbol.iterator](),r={},n("next"),n("throw"),n("return"),r[Symbol.asyncIterator]=function(){return this},r);function n(i){r[i]=e[i]&&function(s){return new Promise(function(a,c){s=e[i](s),o(a,c,s.done,s.value)})}}function o(i,s,a,c){Promise.resolve(c).then(function(f){i({value:f,done:a})},s)}}function A(e){return typeof e=="function"}function at(e){var t=function(n){Error.call(n),n.stack=new Error().stack},r=e(t);return r.prototype=Object.create(Error.prototype),r.prototype.constructor=r,r}var $t=at(function(e){return function(r){e(this),this.message=r?r.length+` errors occurred during unsubscription: -`+r.map(function(n,o){return o+1+") "+n.toString()}).join(` - `):"",this.name="UnsubscriptionError",this.errors=r}});function Ve(e,t){if(e){var r=e.indexOf(t);0<=r&&e.splice(r,1)}}var Ie=function(){function e(t){this.initialTeardown=t,this.closed=!1,this._parentage=null,this._finalizers=null}return e.prototype.unsubscribe=function(){var t,r,n,o,i;if(!this.closed){this.closed=!0;var s=this._parentage;if(s)if(this._parentage=null,Array.isArray(s))try{for(var a=Ee(s),c=a.next();!c.done;c=a.next()){var f=c.value;f.remove(this)}}catch(v){t={error:v}}finally{try{c&&!c.done&&(r=a.return)&&r.call(a)}finally{if(t)throw t.error}}else s.remove(this);var u=this.initialTeardown;if(A(u))try{u()}catch(v){i=v instanceof $t?v.errors:[v]}var p=this._finalizers;if(p){this._finalizers=null;try{for(var m=Ee(p),d=m.next();!d.done;d=m.next()){var h=d.value;try{mn(h)}catch(v){i=i!=null?i:[],v instanceof $t?i=D(D([],W(i)),W(v.errors)):i.push(v)}}}catch(v){n={error:v}}finally{try{d&&!d.done&&(o=m.return)&&o.call(m)}finally{if(n)throw n.error}}}if(i)throw new $t(i)}},e.prototype.add=function(t){var r;if(t&&t!==this)if(this.closed)mn(t);else{if(t instanceof e){if(t.closed||t._hasParent(this))return;t._addParent(this)}(this._finalizers=(r=this._finalizers)!==null&&r!==void 0?r:[]).push(t)}},e.prototype._hasParent=function(t){var r=this._parentage;return r===t||Array.isArray(r)&&r.includes(t)},e.prototype._addParent=function(t){var r=this._parentage;this._parentage=Array.isArray(r)?(r.push(t),r):r?[r,t]:t},e.prototype._removeParent=function(t){var r=this._parentage;r===t?this._parentage=null:Array.isArray(r)&&Ve(r,t)},e.prototype.remove=function(t){var r=this._finalizers;r&&Ve(r,t),t instanceof e&&t._removeParent(this)},e.EMPTY=function(){var t=new e;return t.closed=!0,t}(),e}();var Sr=Ie.EMPTY;function It(e){return e instanceof Ie||e&&"closed"in e&&A(e.remove)&&A(e.add)&&A(e.unsubscribe)}function mn(e){A(e)?e():e.unsubscribe()}var Le={onUnhandledError:null,onStoppedNotification:null,Promise:void 0,useDeprecatedSynchronousErrorHandling:!1,useDeprecatedNextContext:!1};var st={setTimeout:function(e,t){for(var r=[],n=2;n0},enumerable:!1,configurable:!0}),t.prototype._trySubscribe=function(r){return this._throwIfClosed(),e.prototype._trySubscribe.call(this,r)},t.prototype._subscribe=function(r){return this._throwIfClosed(),this._checkFinalizedStatuses(r),this._innerSubscribe(r)},t.prototype._innerSubscribe=function(r){var n=this,o=this,i=o.hasError,s=o.isStopped,a=o.observers;return i||s?Sr:(this.currentObservers=null,a.push(r),new Ie(function(){n.currentObservers=null,Ve(a,r)}))},t.prototype._checkFinalizedStatuses=function(r){var n=this,o=n.hasError,i=n.thrownError,s=n.isStopped;o?r.error(i):s&&r.complete()},t.prototype.asObservable=function(){var r=new F;return r.source=this,r},t.create=function(r,n){return new En(r,n)},t}(F);var En=function(e){ie(t,e);function t(r,n){var o=e.call(this)||this;return o.destination=r,o.source=n,o}return t.prototype.next=function(r){var n,o;(o=(n=this.destination)===null||n===void 0?void 0:n.next)===null||o===void 0||o.call(n,r)},t.prototype.error=function(r){var n,o;(o=(n=this.destination)===null||n===void 0?void 0:n.error)===null||o===void 0||o.call(n,r)},t.prototype.complete=function(){var r,n;(n=(r=this.destination)===null||r===void 0?void 0:r.complete)===null||n===void 0||n.call(r)},t.prototype._subscribe=function(r){var n,o;return(o=(n=this.source)===null||n===void 0?void 0:n.subscribe(r))!==null&&o!==void 0?o:Sr},t}(x);var Et={now:function(){return(Et.delegate||Date).now()},delegate:void 0};var wt=function(e){ie(t,e);function t(r,n,o){r===void 0&&(r=1/0),n===void 0&&(n=1/0),o===void 0&&(o=Et);var i=e.call(this)||this;return i._bufferSize=r,i._windowTime=n,i._timestampProvider=o,i._buffer=[],i._infiniteTimeWindow=!0,i._infiniteTimeWindow=n===1/0,i._bufferSize=Math.max(1,r),i._windowTime=Math.max(1,n),i}return t.prototype.next=function(r){var n=this,o=n.isStopped,i=n._buffer,s=n._infiniteTimeWindow,a=n._timestampProvider,c=n._windowTime;o||(i.push(r),!s&&i.push(a.now()+c)),this._trimBuffer(),e.prototype.next.call(this,r)},t.prototype._subscribe=function(r){this._throwIfClosed(),this._trimBuffer();for(var n=this._innerSubscribe(r),o=this,i=o._infiniteTimeWindow,s=o._buffer,a=s.slice(),c=0;c0?e.prototype.requestAsyncId.call(this,r,n,o):(r.actions.push(this),r._scheduled||(r._scheduled=ut.requestAnimationFrame(function(){return r.flush(void 0)})))},t.prototype.recycleAsyncId=function(r,n,o){var i;if(o===void 0&&(o=0),o!=null?o>0:this.delay>0)return e.prototype.recycleAsyncId.call(this,r,n,o);var s=r.actions;n!=null&&((i=s[s.length-1])===null||i===void 0?void 0:i.id)!==n&&(ut.cancelAnimationFrame(n),r._scheduled=void 0)},t}(Ut);var Tn=function(e){ie(t,e);function t(){return e!==null&&e.apply(this,arguments)||this}return t.prototype.flush=function(r){this._active=!0;var n=this._scheduled;this._scheduled=void 0;var o=this.actions,i;r=r||o.shift();do if(i=r.execute(r.state,r.delay))break;while((r=o[0])&&r.id===n&&o.shift());if(this._active=!1,i){for(;(r=o[0])&&r.id===n&&o.shift();)r.unsubscribe();throw i}},t}(Wt);var Te=new Tn(Sn);var _=new F(function(e){return e.complete()});function Dt(e){return e&&A(e.schedule)}function Cr(e){return e[e.length-1]}function Ye(e){return A(Cr(e))?e.pop():void 0}function Oe(e){return Dt(Cr(e))?e.pop():void 0}function Vt(e,t){return typeof Cr(e)=="number"?e.pop():t}var pt=function(e){return e&&typeof e.length=="number"&&typeof e!="function"};function zt(e){return A(e==null?void 0:e.then)}function Nt(e){return A(e[ft])}function qt(e){return Symbol.asyncIterator&&A(e==null?void 0:e[Symbol.asyncIterator])}function Kt(e){return new TypeError("You provided "+(e!==null&&typeof e=="object"?"an invalid object":"'"+e+"'")+" where a stream was expected. You can provide an Observable, Promise, ReadableStream, Array, AsyncIterable, or Iterable.")}function Ni(){return typeof Symbol!="function"||!Symbol.iterator?"@@iterator":Symbol.iterator}var Qt=Ni();function Yt(e){return A(e==null?void 0:e[Qt])}function Gt(e){return pn(this,arguments,function(){var r,n,o,i;return Pt(this,function(s){switch(s.label){case 0:r=e.getReader(),s.label=1;case 1:s.trys.push([1,,9,10]),s.label=2;case 2:return[4,et(r.read())];case 3:return n=s.sent(),o=n.value,i=n.done,i?[4,et(void 0)]:[3,5];case 4:return[2,s.sent()];case 5:return[4,et(o)];case 6:return[4,s.sent()];case 7:return s.sent(),[3,2];case 8:return[3,10];case 9:return r.releaseLock(),[7];case 10:return[2]}})})}function Bt(e){return A(e==null?void 0:e.getReader)}function U(e){if(e instanceof F)return e;if(e!=null){if(Nt(e))return qi(e);if(pt(e))return Ki(e);if(zt(e))return Qi(e);if(qt(e))return On(e);if(Yt(e))return Yi(e);if(Bt(e))return Gi(e)}throw Kt(e)}function qi(e){return new F(function(t){var r=e[ft]();if(A(r.subscribe))return r.subscribe(t);throw new TypeError("Provided object does not correctly implement Symbol.observable")})}function Ki(e){return new F(function(t){for(var r=0;r=2;return function(n){return n.pipe(e?L(function(o,i){return e(o,i,n)}):de,ge(1),r?He(t):Vn(function(){return new Xt}))}}function zn(){for(var e=[],t=0;t=2,!0))}function pe(e){e===void 0&&(e={});var t=e.connector,r=t===void 0?function(){return new x}:t,n=e.resetOnError,o=n===void 0?!0:n,i=e.resetOnComplete,s=i===void 0?!0:i,a=e.resetOnRefCountZero,c=a===void 0?!0:a;return function(f){var u,p,m,d=0,h=!1,v=!1,G=function(){p==null||p.unsubscribe(),p=void 0},oe=function(){G(),u=m=void 0,h=v=!1},N=function(){var T=u;oe(),T==null||T.unsubscribe()};return y(function(T,Qe){d++,!v&&!h&&G();var De=m=m!=null?m:r();Qe.add(function(){d--,d===0&&!v&&!h&&(p=$r(N,c))}),De.subscribe(Qe),!u&&d>0&&(u=new rt({next:function($e){return De.next($e)},error:function($e){v=!0,G(),p=$r(oe,o,$e),De.error($e)},complete:function(){h=!0,G(),p=$r(oe,s),De.complete()}}),U(T).subscribe(u))})(f)}}function $r(e,t){for(var r=[],n=2;ne.next(document)),e}function K(e,t=document){return Array.from(t.querySelectorAll(e))}function z(e,t=document){let r=ce(e,t);if(typeof r=="undefined")throw new ReferenceError(`Missing element: expected "${e}" to be present`);return r}function ce(e,t=document){return t.querySelector(e)||void 0}function _e(){return document.activeElement instanceof HTMLElement&&document.activeElement||void 0}function er(e){return C(b(document.body,"focusin"),b(document.body,"focusout")).pipe(ke(1),l(()=>{let t=_e();return typeof t!="undefined"?e.contains(t):!1}),V(e===_e()),B())}function Xe(e){return{x:e.offsetLeft,y:e.offsetTop}}function Qn(e){return C(b(window,"load"),b(window,"resize")).pipe(Ce(0,Te),l(()=>Xe(e)),V(Xe(e)))}function tr(e){return{x:e.scrollLeft,y:e.scrollTop}}function dt(e){return C(b(e,"scroll"),b(window,"resize")).pipe(Ce(0,Te),l(()=>tr(e)),V(tr(e)))}var Gn=function(){if(typeof Map!="undefined")return Map;function e(t,r){var n=-1;return t.some(function(o,i){return o[0]===r?(n=i,!0):!1}),n}return function(){function t(){this.__entries__=[]}return Object.defineProperty(t.prototype,"size",{get:function(){return this.__entries__.length},enumerable:!0,configurable:!0}),t.prototype.get=function(r){var n=e(this.__entries__,r),o=this.__entries__[n];return o&&o[1]},t.prototype.set=function(r,n){var o=e(this.__entries__,r);~o?this.__entries__[o][1]=n:this.__entries__.push([r,n])},t.prototype.delete=function(r){var n=this.__entries__,o=e(n,r);~o&&n.splice(o,1)},t.prototype.has=function(r){return!!~e(this.__entries__,r)},t.prototype.clear=function(){this.__entries__.splice(0)},t.prototype.forEach=function(r,n){n===void 0&&(n=null);for(var o=0,i=this.__entries__;o0},e.prototype.connect_=function(){!Dr||this.connected_||(document.addEventListener("transitionend",this.onTransitionEnd_),window.addEventListener("resize",this.refresh),ga?(this.mutationsObserver_=new MutationObserver(this.refresh),this.mutationsObserver_.observe(document,{attributes:!0,childList:!0,characterData:!0,subtree:!0})):(document.addEventListener("DOMSubtreeModified",this.refresh),this.mutationEventsAdded_=!0),this.connected_=!0)},e.prototype.disconnect_=function(){!Dr||!this.connected_||(document.removeEventListener("transitionend",this.onTransitionEnd_),window.removeEventListener("resize",this.refresh),this.mutationsObserver_&&this.mutationsObserver_.disconnect(),this.mutationEventsAdded_&&document.removeEventListener("DOMSubtreeModified",this.refresh),this.mutationsObserver_=null,this.mutationEventsAdded_=!1,this.connected_=!1)},e.prototype.onTransitionEnd_=function(t){var r=t.propertyName,n=r===void 0?"":r,o=va.some(function(i){return!!~n.indexOf(i)});o&&this.refresh()},e.getInstance=function(){return this.instance_||(this.instance_=new e),this.instance_},e.instance_=null,e}(),Bn=function(e,t){for(var r=0,n=Object.keys(t);r0},e}(),Xn=typeof WeakMap!="undefined"?new WeakMap:new Gn,Zn=function(){function e(t){if(!(this instanceof e))throw new TypeError("Cannot call a class as a function.");if(!arguments.length)throw new TypeError("1 argument required, but only 0 present.");var r=ya.getInstance(),n=new Aa(t,r,this);Xn.set(this,n)}return e}();["observe","unobserve","disconnect"].forEach(function(e){Zn.prototype[e]=function(){var t;return(t=Xn.get(this))[e].apply(t,arguments)}});var Ca=function(){return typeof rr.ResizeObserver!="undefined"?rr.ResizeObserver:Zn}(),eo=Ca;var to=new x,Ra=$(()=>k(new eo(e=>{for(let t of e)to.next(t)}))).pipe(g(e=>C(ze,k(e)).pipe(R(()=>e.disconnect()))),J(1));function he(e){return{width:e.offsetWidth,height:e.offsetHeight}}function ye(e){return Ra.pipe(S(t=>t.observe(e)),g(t=>to.pipe(L(({target:r})=>r===e),R(()=>t.unobserve(e)),l(()=>he(e)))),V(he(e)))}function bt(e){return{width:e.scrollWidth,height:e.scrollHeight}}function ir(e){let t=e.parentElement;for(;t&&(e.scrollWidth<=t.scrollWidth&&e.scrollHeight<=t.scrollHeight);)t=(e=t).parentElement;return t?e:void 0}var ro=new x,ka=$(()=>k(new IntersectionObserver(e=>{for(let t of e)ro.next(t)},{threshold:0}))).pipe(g(e=>C(ze,k(e)).pipe(R(()=>e.disconnect()))),J(1));function ar(e){return ka.pipe(S(t=>t.observe(e)),g(t=>ro.pipe(L(({target:r})=>r===e),R(()=>t.unobserve(e)),l(({isIntersecting:r})=>r))))}function no(e,t=16){return dt(e).pipe(l(({y:r})=>{let n=he(e),o=bt(e);return r>=o.height-n.height-t}),B())}var sr={drawer:z("[data-md-toggle=drawer]"),search:z("[data-md-toggle=search]")};function oo(e){return sr[e].checked}function Ke(e,t){sr[e].checked!==t&&sr[e].click()}function Ue(e){let t=sr[e];return b(t,"change").pipe(l(()=>t.checked),V(t.checked))}function Ha(e,t){switch(e.constructor){case HTMLInputElement:return e.type==="radio"?/^Arrow/.test(t):!0;case HTMLSelectElement:case HTMLTextAreaElement:return!0;default:return e.isContentEditable}}function Pa(){return C(b(window,"compositionstart").pipe(l(()=>!0)),b(window,"compositionend").pipe(l(()=>!1))).pipe(V(!1))}function io(){let e=b(window,"keydown").pipe(L(t=>!(t.metaKey||t.ctrlKey)),l(t=>({mode:oo("search")?"search":"global",type:t.key,claim(){t.preventDefault(),t.stopPropagation()}})),L(({mode:t,type:r})=>{if(t==="global"){let n=_e();if(typeof n!="undefined")return!Ha(n,r)}return!0}),pe());return Pa().pipe(g(t=>t?_:e))}function le(){return new URL(location.href)}function ot(e){location.href=e.href}function ao(){return new x}function so(e,t){if(typeof t=="string"||typeof t=="number")e.innerHTML+=t.toString();else if(t instanceof Node)e.appendChild(t);else if(Array.isArray(t))for(let r of t)so(e,r)}function M(e,t,...r){let n=document.createElement(e);if(t)for(let o of Object.keys(t))typeof t[o]!="undefined"&&(typeof t[o]!="boolean"?n.setAttribute(o,t[o]):n.setAttribute(o,""));for(let o of r)so(n,o);return n}function cr(e){if(e>999){let t=+((e-950)%1e3>99);return`${((e+1e-6)/1e3).toFixed(t)}k`}else return e.toString()}function co(){return location.hash.substring(1)}function Vr(e){let t=M("a",{href:e});t.addEventListener("click",r=>r.stopPropagation()),t.click()}function $a(){return b(window,"hashchange").pipe(l(co),V(co()),L(e=>e.length>0),J(1))}function fo(){return $a().pipe(l(e=>ce(`[id="${e}"]`)),L(e=>typeof e!="undefined"))}function zr(e){let t=matchMedia(e);return Zt(r=>t.addListener(()=>r(t.matches))).pipe(V(t.matches))}function uo(){let e=matchMedia("print");return C(b(window,"beforeprint").pipe(l(()=>!0)),b(window,"afterprint").pipe(l(()=>!1))).pipe(V(e.matches))}function Nr(e,t){return e.pipe(g(r=>r?t():_))}function fr(e,t={credentials:"same-origin"}){return ue(fetch(`${e}`,t)).pipe(fe(()=>_),g(r=>r.status!==200?Tt(()=>new Error(r.statusText)):k(r)))}function We(e,t){return fr(e,t).pipe(g(r=>r.json()),J(1))}function po(e,t){let r=new DOMParser;return fr(e,t).pipe(g(n=>n.text()),l(n=>r.parseFromString(n,"text/xml")),J(1))}function ur(e){let t=M("script",{src:e});return $(()=>(document.head.appendChild(t),C(b(t,"load"),b(t,"error").pipe(g(()=>Tt(()=>new ReferenceError(`Invalid script: ${e}`))))).pipe(l(()=>{}),R(()=>document.head.removeChild(t)),ge(1))))}function lo(){return{x:Math.max(0,scrollX),y:Math.max(0,scrollY)}}function mo(){return C(b(window,"scroll",{passive:!0}),b(window,"resize",{passive:!0})).pipe(l(lo),V(lo()))}function ho(){return{width:innerWidth,height:innerHeight}}function bo(){return b(window,"resize",{passive:!0}).pipe(l(ho),V(ho()))}function vo(){return Q([mo(),bo()]).pipe(l(([e,t])=>({offset:e,size:t})),J(1))}function pr(e,{viewport$:t,header$:r}){let n=t.pipe(Z("size")),o=Q([n,r]).pipe(l(()=>Xe(e)));return Q([r,t,o]).pipe(l(([{height:i},{offset:s,size:a},{x:c,y:f}])=>({offset:{x:s.x-c,y:s.y-f+i},size:a})))}(()=>{function e(n,o){parent.postMessage(n,o||"*")}function t(...n){return n.reduce((o,i)=>o.then(()=>new Promise(s=>{let a=document.createElement("script");a.src=i,a.onload=s,document.body.appendChild(a)})),Promise.resolve())}var r=class extends EventTarget{constructor(n){super(),this.url=n,this.m=i=>{i.source===this.w&&(this.dispatchEvent(new MessageEvent("message",{data:i.data})),this.onmessage&&this.onmessage(i))},this.e=(i,s,a,c,f)=>{if(s===`${this.url}`){let u=new ErrorEvent("error",{message:i,filename:s,lineno:a,colno:c,error:f});this.dispatchEvent(u),this.onerror&&this.onerror(u)}};let o=document.createElement("iframe");o.hidden=!0,document.body.appendChild(this.iframe=o),this.w.document.open(),this.w.document.write(` - - - -Redirecting... - - diff --git a/en/site/authentication-and-authorization/configure-mutual-tls-between-components/index.html b/en/site/authentication-and-authorization/configure-mutual-tls-between-components/index.html deleted file mode 100644 index 57aba8b59..000000000 --- a/en/site/authentication-and-authorization/configure-mutual-tls-between-components/index.html +++ /dev/null @@ -1,3192 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - Configure Mutual TLS Between Components - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- - - -
- - - - - - -
- - -
- -
- - - - - - - -
-
- - - -
-
-
- - - - -
-
-
- - - -
-
-
- - - -
-
-
- - - -
-
- - - - - - - - - - - - - - - - - - - - -

Configure Mutual TLS Between Components

-

Mutual transport layer security (mutual TLS) is a protocol that ensures privacy, integrity, and authentication of the data transmitted between two endpoints. In mutual TLS, the client and the server authenticate each other using digital certificates, establishing trust and verifying identities. Upon successful authentication, mutual TLS encrypts the data exchanged between the client and the server, preventing unauthorized access.

-

In Choreo, you can use mutual TLS to establish secure connections between components within a project.

-
-

Note

-

If mutual TLS is not required, you can configure TLS instead. TLS provides a secure communication channel between a client and server but does not require the client to present a certificate to the server. This results in the absence of mutual authentication between the client and the server. While TLS ensures the confidentiality of data transmitted between the client and server, preventing unauthorized tampering, mutual TLS enhances TLS by introducing client-side authentication and facilitating mutual verification of identities between the client and server.

-

To configure TLS, you can follow the same steps as for mutual TLS as mentioned below, without having to generate a client certificate. The client only needs the root certificate to verify the server's identity.

-
-

Generate certificates to establish mutual TLS

-
    -
  • -

    Root certificate: Trusted by both the client and the server, this certificate is used to verify the authenticity of other certificates presented during the mutual TLS handshake process and to issue certificates for clients and servers. For a specific project, you can generate a single root certificate using a tool like OpenSSL.

    -
    • -
  • -

    Client certificate: Contains the client’s identity for authentication. The common name (CN) in the certificate identifies the client. The generated client certificate must be signed by the root certificate.

    -
    • -
  • -

    Server certificate: Clients use the server certificate to verify the trustworthiness of the server and establish a secure and authenticated connection. Similar to the client certificates, the server certificate must also be signed by the root certificate. When generating the server certificate, you must specify the server's hostname for the subject alternative name (SAN). You can obtain the hostname for the specific version of a service component from any project endpoint on the Overview page.

    -
    • -
-

For example, if your project endpoint is http://my-service-3781140846:7080/todos, the hostname will be my-service-3781140846.

-

Read mutual TLS certificates from your component

-

The approach to read mutual TLS certificates from a component can vary depending on its implementation. Typically, a component can read the certificate data from the file system or via an environment variable. For detailed instructions on adding environment variables and file mounts to your application, see Manage Configurations and Secrets.

-
-

Info

-

When you specify a private key, ensure you save it as a secret.

-
-

Sample for mutual TLS communication

-

For a sample that demonstrates how you can deploy services that communicate using mutual TLS, see service-to-service-mtls.

- - - - - - -
-
- - -
- - - -
- - -
- - - -
-
-
- - - - - - - - - - - - - - - - - \ No newline at end of file diff --git a/en/site/authentication-and-authorization/pass-end-user-attributes-to-upstream-services/index.html b/en/site/authentication-and-authorization/pass-end-user-attributes-to-upstream-services/index.html deleted file mode 100644 index 44b4f21bf..000000000 --- a/en/site/authentication-and-authorization/pass-end-user-attributes-to-upstream-services/index.html +++ /dev/null @@ -1,3445 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - Pass End-User Attributes to Upstream Services - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- - - -
- - - - - - -
- - -
- -
- - - - - - - -
-
- - - -
-
-
- - - - -
-
-
- - - -
-
-
- - - -
-
-
- - - -
-
- - - - - - - - - - - - - - - - - - - - -

Pass End-User Attributes to Upstream Services

-

There are scenarios where a backend service needs to apply specific logic or make decisions depending on the user consuming an API. In such scenarios, you must pass end-user attributes to the backend during an API call.

-

Choreo provides a method to send user information to a backend service through a JSON Web Token (JWT) in an HTTP header of an API request.

-

How it works

-

The backend JWT contains claims transferred between the parties, such as the user and the backend. A claim can be metadata of the request or data about the user. A set of claims is called a dialect, for example, http://wso2.org/claims.

-

For each API request, a digitally signed JWT is carried to the backend service in the following format to ensure that the authenticity of the claims list is verified:

-

{token header}.{claims list}.{signature}

-

When a request goes through Choreo, the backend JWT is appended as the X-JWT-Assertion header in the outgoing message. The backend service fetches the JWT and retrieves the required information about the user, application, or token.

-

Claims

-

Claims are fragments of information included in the JWT.

-

The following is a sample claim set added to the end-user token for an access token generated via the authorization code:

-
-

Tip

-

This access token is generated via Asgardeo using the authorization code grant type. Here, the Asgardeo application is configured to include the email claim in the token.

-
-
{
-  "sub": "11f53c32-f8ac-4810-bb79-615b2184baf5",
-  "http://wso2.org/claims/apiname": "JWT Test - Endpoint 9090 803",
-  "http://wso2.org/claims/applicationtier": "Unlimited",
-  "http://wso2.org/claims/version": "1.0.0",
-  "http://wso2.org/claims/keytype": "PRODUCTION",
-  "iss": "wso2.org/products/am",
-  "http://wso2.org/claims/applicationname": "jwtTest2",
-  "http://wso2.org/claims/enduserTenantId": "0",
-  "http://wso2.org/claims/applicationUUId": "45101ccb-865f-4f48-b7ac-18e43b07edd3",
-  "client_id": "IMJB5ZiR1dHQYBdiMIRAGis1WToa",
-  "http://wso2.org/claims/subscriber": "5f4a7105-a889-4f92-9612-eef5bafe4eec",
-  "azp": "IMJB5ZiR1dHQYBdiMIRAGis1WToa",
-  "org_id": "b554e001-761c-4d3a-a7a6-a61d73d34221",
-  "http://wso2.org/claims/tier": "Unlimited",
-  "scope": "email openid profile",
-  "exp": 1690537362,
-  "http://wso2.org/claims/applicationid": "45101ccb-865f-4f48-b7ac-18e43b07edd3",
-  "http://wso2.org/claims/usertype": "Application_User",
-  "org_name": "test",
-  "iat": 1690533762,
-  "email": "testmail@gmail.com",
-  "jti": "69558555-d386-4a81-9ca0-0a23f809cd3c",
-  "http://wso2.org/claims/apicontext": "/b554e001-761c-4d3a-a7a6-a61d73d34221/swog/jwt-test/endpoint-9090-803/1.0.0"
-}
-
- -

The following table describes the information contained in the sample JWT claims set given above:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Claim NameDescriptionMandatory/Optional
iatThe time the token was issued.Mandatory
jtiThe unique token identifier.Mandatory
expThe token expiry time.Mandatory
issThe issuer of the token.Mandatory
http://wso2.org/claims/apinameThe name of the API in Choreo.Optional
http://wso2.org/claims/versionThe API version.Optional
http://wso2.org/claims/keytypeThe environment in Choreo that the API is in (Development or production).Optional
http://wso2.org/claims/apicontextThe API context in Choreo.Optional
http://wso2.org/claims/subscriberThe subscriber to the API, usually the app developer.Optional
http://wso2.org/claims/applicationnameThe application through which the API invocation is done.Optional
http://wso2.org/claims/applicationidThe ID of the application through which the API invocation is done.Optional
http://wso2.org/claims/applicationUUIdThe UUID of the application.Optional
client_idThe client identifier. This is copied from the original token.Optional
azpThe authorized party (the party to which the ID token was issued). This is copied from the original token.Optional
org_idThe organization ID. This is copied from the original token.Optional
org_nameThe organization name. This is copied from the original token.Optional
http://wso2.org/claims/tierThe tier/price band for the subscription.Optional
scopeThe scope of the token. This is copied from the original token.Optional
http://wso2.org/claims/usertypeThe type of application user whose action invoked the API.Optional
emailThe email address of the user. This is copied from the original token.Optional
-
-

Note

-

The claims that get added to the end-user token can vary depending on the grant type used when generating the access token. For example, if you use the client-credentials grant type to generate the access token, the generated backend JWT would contain the following information:

-
{ 
-  "http://wso2.org/claims/apiname": "DefaultAPI", 
-  "http://wso2.org/claims/version": "1.0.0", 
-  "http://wso2.org/claims/keytype": "PRODUCTION", 
-  "iss": "wso2.org/products/am", 
-  "http://wso2.org/claims/enduserTenantId": "0", 
-  "exp": 1673245727, 
-  "http://wso2.org/claims/usertype": "Application_User", 
-  "iat": 1673242127, 
-  "jti": "6e3f4392-8bd9-4900-9d08-eaab7429c510", 
-  "http://wso2.org/claims/apicontext": "/9e71ab5e-6df5-4727-92d2-80ecf1a6218d/qbky/default/1.0.0" 
-}
-
- -
-

To verify the authenticity of claims in a JWT, the claims must be validated using the public key corresponding to the private key used to sign the JWT.

-

JSON web key set (JWKS) is a set of keys to validate a JWT. It contains a collection of JSON web keys, which are public keys used to verify the signature of a JWT.

-

Typically, when a third party (such as an identity provider)issues a JWT and the recipient needs to verify its signature, they can use a JWKS. -JWKS allows the issuer to rotate keys dynamically rather than hard-coding the public key in the application. The recipient can obtain the public key by accessing the JWKS endpoint.

-

JWKS support in Choreo to validate the JWT

-

Choreo provides an endpoint to specify the public keys for backend JWT validation. Here are the endpoint URLs for the US East and EU regions:

- -
-

Note

-

For private data planes (PDPs), use the following JWKS endpoint URL template:

-

https://<PDP_GATEWAY_DOMAIN>/.wellknown/jwks

-

Be sure to replace <PDP-GATEWAY-DOMAIN> with the default domain configured to access the PDP APIs.

-
-

The endpoint provides one or more signing keys to validate the JWT. -The JSON web keys have a kid identifier that can be matched with the same property on the JWT to decide which key to use when validating.

-

The following is a sample JWKS response:

-
{
-   "keys": [
-       {
-           "kty": "RSA",
-           "e": "AQAB",
-           "use": "sig",
-           "kid": "ZjcwNmI2ZDJmNWQ0M2I5YzZiYzJmZmM4YjMwMDFlOTA4MGE3ZWZjZTMzNjU3YWU1MzViYjZkOTkzZjYzOGYyNg",
-           "alg": "RS256",
-           "n": "8vjeHzRhvpfMystncPnLBWy_t5F3eCxbcLbdugWnzfnIgaV6TWnqPBUagJBKpzRZs4A9Qja_ZrSVJjYsbARzCS_qiWp0Cdwkqn6ZCXpmbpfjYnKORq8N8M-zWaSZYbNvWJ5oSO4kH-LKWzODaFebwTJBpsR1vChHH95doxFuUjiZaisVaQgUJ6drRdlDtImp9r9EAX36YROuYFPoEJcvsH4_uuAR6ClJ12RE3M-YN4NTi1waVNvGbz43oNrpPy7SXgpizingxSGMqI6WU2ysRmk_f9ALgiPIpFDpufiCTYaIcRT-YcUyp9nMDlTRskMuD-dQ1sdJOa11P_yMs-glfQ"
-       }
-   ]
-}
-
- -

The following table describes the information contained in the JWKS response:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
PropertyDescription
ktyThe cryptographic family to which the key belongs.
Choreo only supports RSA.
eThe exponent value of the public key.
useThe purpose of the key. For example, whether it is for signing or encryption.
kidThe identification parameter to match a specific key.
algThe algorithm to use with the key.
nThe modulus value of the public key.
-

Enable passing end-user attributes to the backend

-

To enable passing end-user attributes to the backend through API calls via Choreo, follow the steps given below:

-
    -
  1. Sign in to the Choreo Console.
    2. -
  2. In the Components Listing pane, click on the component for which you want to pass end-user attributes to the backend.
    3. -
  3. In the left navigation menu, click Deploy.
    4. -
  4. -

    Go to the Set Up card and click Endpoint Configurations. This opens the Endpoint Configurations pane.

    -
    -

    Note

    -

    If the component is an API Proxy, go to the Build Area card and click Security Settings. This opens the Security Settings pane.

    -
    -
    5. -
  5. -

    Select the Pass Security Context To Backend checkbox.

    -
    6. -
  6. -

    Optionally, specify appropriate audience values in the End User Token Audiences field. Specifying values restricts the JWT to the respective audiences, enabling the backend service to validate and confirm the intended recipients, including itself.

    -
    -

    Note

    -

    The backend JWT does not include the audience field (aud) by default.

    -
    -
    7. -
  7. -

    Click Apply.

    -
    8. -
  8. To redeploy the component with the applied setting, go to the Set Up card and click Deploy.
    9. -
- - - - - - -
-
- - -
- - - -
- - -
- - - -
-
-
- - - - - - - - - - - - - - - - - \ No newline at end of file diff --git a/en/site/authentication-and-authorization/secure-api-access-with-asgardeo/index.html b/en/site/authentication-and-authorization/secure-api-access-with-asgardeo/index.html deleted file mode 100644 index 9387ab073..000000000 --- a/en/site/authentication-and-authorization/secure-api-access-with-asgardeo/index.html +++ /dev/null @@ -1,3299 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - Secure API Access with Asgardeo - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- - - -
- - - - - - -
- - -
- -
- - - - - - - -
-
- - - -
-
-
- - - - -
-
-
- - - -
-
-
- - - -
-
-
- - - -
-
- - - - - - - - - - - - - - - - - - - - -

Secure API Access with Asgardeo

-

API security refers to the measures and practices used to protect Application Programming Interfaces (APIs) from potential threats and vulnerabilities. APIs are essential for enabling communication and data exchange between different software applications and services, making them a critical component in modern software development. However, their openness and accessibility can also make them targets for various security risks. Authentication and authorization are key aspects of API security. Authentication is ensuring that only authorized users or applications can access the API. This can involve using API keys, tokens, or more advanced authentication methods like OAuth 2.0. Authorization is controlling what authenticated users or applications are allowed to do within the API. Authorization mechanisms restrict access to specific resources and actions based on user roles or permissions.

-

Organizations using Asgardeo for identity and access management (IAM) can seamlessly integrate it with Choreo as an external Identity Provider (IdP). This guide will walk you through setting up Choreo to authenticate API invocations through Asgardeo which is configured as an external IdP.

-

This guide walks you through the following steps:

-
    -
  • Assign scopes to an API in Choreo.
    • -
  • Create an API in Asgardeo.
    • -
  • Create an application in Asgardeo and consume the Asgardeo API.
    • -
  • Create an application in Choreo and enable external IdP authentication.
    • -
  • Invoke the API with scopes.
    • -
-

Prerequisites

-

To follow this guide, you need to satisfy the following prerequisites:

- -

Step 1: Assign scopes to an API in Choreo

-

You can provide fine-grained access control to your API resources with scopes. Follow the steps below to assign a scope to the resources in the API:

-
    -
  1. In the Component Listing pane, click on the component you want to attach scopes to.
    2. -
  2. In the left navigation menu, click Manage and then Permissions.
    3. -
  3. Click + Add Permission (Scope).
    4. -
  4. In the Permission List pane, enter the permission value and click + Add New.
    5. -
  5. Click the copy icon in front of the added scope to copy the fully qualified name of the scope. Save this value for future reference.
    6. -
  6. To attach a scope to a resource, click the Select Permissions list under the respective resource, and select the scopes you wish to attach.
    7. -
  7. Click Save and Deploy.
    8. -
  8. In the left navigation, click Manage and then Lifecycle.
    9. -
  9. Click Publish and continue to publish your API to the Choreo Developer Portal.
    10. -
-

Step 2: Create an API and an application in Asgardeo

-

Follow the Asgardeo API Authorization guide to create an application and an API in Asgardeo and to enable API authorization.

-
-

Note

-
    -
  • Use the fully qualified name of the scope when adding scopes.
    • -
  • Do the following under the protocol tab:
      -
    • Select JWT as the Access Token.
      • -
    • Select the appropriate grant types.
      • -
    • Copy the client ID and client secret of the application for future reference.
      • -
    -
    • -
-
-

Step 3: Create an application in Choreo and enable external IdP authentication

-

Follow the steps below to consume the Choreo API and use an external IdP for authentication:

-
    -
  1. Sign in to the Choreo Developer Portal at https://devportal.choreo.dev.
    2. -
  2. Click Applications. and then click +Create.
    3. -
  3. Enter a name and description for the application.
    4. -
  4. Click Create.
    5. -
  5. In the left navigation, under Credentials and click Production.
    6. -
  6. Select the Identity Provider as Asgardeo.
    7. -
  7. Enter the Client ID you copied in step 2.
    8. -
  8. -

    Click +Add.

    -
    -

    Note

    -
      -
    • You can only use the Client ID in one application.
      • -
    • The Identity Provider dropdown is visible only to organizations where you have configured external IdPs.
      • -
    -
    -
    9. -
  9. -

    In the left navigation menu, click Subscriptions.

    -
    10. -
  10. In the Subscription Management pane that opens, click + Add APIs.
    11. -
  11. Select the API you assigned scopes to in step 1 and click Add.
    12. -
-

Step 4: Invoke the Choreo API with scopes

-
    -
  1. On the Choreo Developer Portal, go to your application.
    2. -
  2. In the left navigation menu, under Credentials and click Production.
    3. -
  3. Under Endpoints, copy the Token Endpoint URL.
    4. -
  4. -

    Obtain an access token by invoking the token endpoint as follows:

    -
    -

    Note

    -
      -
    • If you are using the production credentials, you need to deploy your component(endpoint) to the production environment by promoting it from the development environment.
      • -
    • If you are using the sandbox credentials, you can use the endpoints deployed in the development environment.
      • -
    -
    -
    -
    -
    -
    curl -X POST '<TOKEN_ENDPOINT>?grant_type=password&scope=<REQUIRED_SCOPES>&username=<USER_NAME>&password=<USER_PASSWORD>' \
- --header 'Content-Type: application/x-www-form-urlencoded' \
- --header 'Authorization: Basic <BASE64-ENCODED ASGARDEO_APP_CLIENT_ID:ASGARDEO_APP_CLIENT_SECRET>'
-
    - -
    -
    -
    curl -X POST 'https://dev.api.asgardeo.io/t/orgHandle/oauth2/token?grant_type=password&scope=<REQUIRED_SCOPES>&username=<USER_NAME>&password=<USER_PASSWORD>' \
---header 'Content-Type: application/x-www-form-urlencoded' \
---header 'Authorization: Basic <BASE64-ENCODED CLIENT_ID:CLIENT_SECRET>'
-
    - -
    -
    -
    -
    5. -
  5. -

    Once you receive the access token, you can test invoking the resource using the OpenAPI console in Choreo by specifying the scope.

    -
    6. -
- - - - - - -
-
- - -
- - - -
- - -
- - - -
-
-
- - - - - - - - - - - - - - - - - \ No newline at end of file diff --git a/en/site/authentication-and-authorization/secure-api-access-with-azure-ad/index.html b/en/site/authentication-and-authorization/secure-api-access-with-azure-ad/index.html deleted file mode 100644 index 3942247d7..000000000 --- a/en/site/authentication-and-authorization/secure-api-access-with-azure-ad/index.html +++ /dev/null @@ -1,3473 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - Secure API Access with Azure - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- - - -
- - - - - - -
- - -
- -
- - - - - - - -
-
- - - -
-
-
- - - - -
-
-
- - - -
-
-
- - - -
-
-
- - - -
-
- - - - - - - - - - - - - - - - - - - - -

Secure API Access with Microsoft Azure Active Directory (Azure AD)

-

API security refers to the measures and practices used to protect Application Programming Interfaces (APIs) from potential threats and vulnerabilities. Authentication and authorization are key aspects of API security. Authentication is ensuring that only authorized users or applications can access the API. This can involve using API keys, tokens, or more advanced authentication methods like OAuth 2.0. Authorization is controlling what authenticated users or applications are allowed to do within the API. Authorization mechanisms restrict access to specific resources and actions based on user roles or permissions.

-

Organizations using Microsoft Azure AD for identity and access management (IAM) can seamlessly integrate it with Choreo as an external Identity Provider (IdP). This guide will walk you through setting up Choreo to authenticate API invocations through Azure AD which is configured as an external IdP.

-

This guide walks you through the following steps:

-
    -
  • Assign scopes to an API in Choreo.
    • -
  • Create an API in Azure AD.
    • -
  • Create an application in Azure AD and consume the Azure API.
    • -
  • Create an application in Choreo and enable external IdP authentication.
    • -
  • Invoke the API with scopes.
    • -
-

Prerequisites

-

To follow this guide, you need to satisfy the following prerequisites:

- -

Step 1: Assign scopes to an API in Choreo

-

You can provide fine-grained access control to your API resources with scopes. Follow the steps below to assign a scope to the resources in the API:

-
    -
  1. In the Component Listing pane, click on the component you want to attach scopes to.
    2. -
  2. In the left navigation menu, click Manage and then Permissions.
    3. -
  3. Click + Add Permission (Scope).
    4. -
  4. In the Permission List pane, enter the permission value and click + Add New.
    5. -
  5. Click the copy icon in front of the added scope to copy the fully qualified name of the scope. Save this value for future reference.
    6. -
  6. To attach a scope to a resource, click the Select Permissions list under the respective resource, and select the scopes you wish to attach.
    7. -
  7. Click Save and Deploy.
    8. -
  8. In the left navigation menu, click Manage and then Lifecycle.
    9. -
  9. Click Publish and continue to publish your API to the Choreo Developer Portal.
    10. -
-

Step 2: Create a web API on Azure AD

-

To enable external IdP authentication for APIs, create an API on Azure AD that represents the API on Choreo. Follow the steps below:

-
    -
  1. Sign in to the Azure console.
    2. -
  2. Follow the Azure guide to create a Web API that represents your API on Choreo.
    3. -
  3. In the left navigation menu, under Manage, select Expose an API.
    4. -
  4. Add the default Application ID URI and click Save and Continue.
    5. -
  5. Under Scopes defined by this API, select Add a scope.
    6. -
  6. Enter the fully qualified name as the scope name.
    7. -
  7. Define who can consent. You can alternatively add a scope requiring admin consent.
    8. -
  8. Enter appropriate values and click Add Scope.
    9. -
-

For more information, refer to the Azure documentation:

- -

Step 2.1: Assign users to the web API

-

You can restrict users to the API as follows:

-
    -
  1. Go to your Azure AD main menu.
    2. -
  2. Under Manage, click on Enterprise Applications. Alternatively, on Microsoft Entra, under Applications, click Enterprise Applications.
    3. -
  3. Select your API.
    4. -
  4. Under Manage, select the Users and groups then select + Add user/group.
    5. -
  5. Select the users and groups and click Select.
    6. -
-

For more information, refer to the Azure documentation: Assign the app to users and groups to restrict access

-

Step 3: Create a client application on Azure AD and invoke the Azure web API

-

To expose the API to application developers, create an application in Azure AD. This application provides you with a client-id and client-secret that your application needs to use to invoke the API.

-

Step 3.1: Create a client application

-

Follow the steps below to create the application:

-
    -
  1. Follow the steps in Register an application on Azure to create an application.
    2. -
  2. -

    Configure the platform settings. Enter your client application's redirect URI in the process.

    -
    -

    Note

    -

    OAuth2 Authorization Grant flow applies to Web Applications.

    -
    -
    3. -
-

Step 3.2: Consume the Azure AD web API from the Azure AD application

-

Once you create the application, select the API and the scopes you want the application to consume. Follow the steps below:

-
    -
  1. Go to Azure Active Directory and then click App registrations.
    2. -
  2. Select your client application (not your web API).
    3. -
  3. In the left navigation menu, click API permissions.
    4. -
  4. Click + Add a permission and select My APIs.
    5. -
  5. Select the API and the required scopes and click Add Permissions.
    6. -
  6. Once you add the scope, click on the scope and copy the scope name and keep it for future reference. Use this as the scope when you invoke the authorize and token endpoint in step 5.
    7. -
-

For more information, refer to the Azure documentation: Add permissions to access your web API

-

Step 3.3: Create secrets for the Azure web application

-

To invoke the application, provide client secrets to the consuming application. Follow the steps below to generate the credentials:

-
    -
  1. In the left navigation menu, click Certificates & Secrets.
    2. -
  2. Click + New client secret.
    3. -
  3. Provide a meaningful description and the required expiration.
    4. -
  4. Click Add.
    5. -
  5. Copy the created Secret ID and Value for future reference.
    6. -
  6. In the left navigation menu, click Overview and open the overview page of the API.
    7. -
  7. Copy the Application (client) ID and save it for future reference.
    8. -
-

For more information, refer to the Azure documentation: Add a Client Secret

-

Step 4: Create an application in Choreo and enable external IdP authentication.

-

Follow the steps below to consume the Choreo API and use an external IdP for authentication:

-
    -
  1. Sign in to the Choreo Developer Portal at https://devportal.choreo.dev.
    2. -
  2. Click Applications. and then click +Create.
    3. -
  3. Enter a name and description for the application.
    4. -
  4. Click Create.
    5. -
  5. In the left navigation menu, under Credentials and click Production.
    6. -
  6. Select your AzureAD (Microsoft) configuration as the Identity Provider.
    7. -
  7. Enter the Application (client) ID you copied in at Step 3.2 as the Client ID.
    8. -
  8. -

    Click +Add.

    -
    -

    Note

    -
      -
    • You can only use the Client ID in one application.
      • -
    • The Identity Provider dropdown is visible only to organizations where you have configured external IdPs.
      • -
    -
    -
    9. -
  9. -

    In the left navigation menu, click Subscriptions.

    -
    10. -
  10. In the Subscription Management pane that opens, click + Add APIs.
    11. -
  11. Select the API you assigned scopes to in step 1 and click Add.
    12. -
-

Step 5: Invoke the API with scopes

-

You can now invoke the Choreo API using the authorization code grant. Choreo will authenticate the user with Azure AD and provide access to the resource.

-
    -
  1. On the Choreo Developer Portal, go to your application.
    2. -
  2. In the left navigation menu, under Credentials and click Production.
    3. -
  3. Under Endpoints, copy the Authorize Endpoint URL.
    4. -
  4. -

    Invoke the authorization endpoint as follows:

    -
    -
    -
    -
    {authorize_url}?client_id={client_id}&redirect_uri={redirect_url}&scope={scopes}&response_mode=query&response_type=code
-
    - -
    -
    -
    https://login.microsoftonline.com/dd912d48-b0be-401f-b18c-8ca89e9c0b6c/oauth2/authorize?client_id=5eb1de74-e449-4973-a620-52c4dc9157a9&redirect_uri=https://localhost:9000&scope=api://580b40b7-5513-4714-a4e0-8d4e784f7dc6/urn:taylordean:books:books_addt&response_mode=query&response_type=code
-
    - -
    -
    -
    -
      -
    1. Review the consent in the login screens that prompt and continue.
      2. -
    2. After you log in, you will receive an authorization code in the URL. Copy the authorization code and use it to get an access token from Azure AD by following the next steps.
      3. -
    3. On the Choreo Developer Portal, go to your application.
      4. -
    4. In the left navigation menu, under Credentials and click Production.
      5. -
    5. Under Endpoints, copy the Token Endpoint URL.
      6. -
    6. Invoke the token endpoint as follows:
      7. -
    -
    -
    -
    -
    curl -X POST -H 'Content-Type: application/x-www-form-urlencoded' \
-{token_endpoint} \
--d 'client_id={client_id}' \
--d 'scope={scopes}' \
--d 'code={authorization_code}' \
--d 'redirect_uri={redirect_url}' \
--d 'client_secret={The client_secret value you copied from the Azure Application}'
--d 'grant_type=authorization_code' \    
-
    - -
    -
    -
    curl -X POST -H 'Content-Type: application/x-www-form-urlencoded' \
-https://login.microsoftonline.com/dd912d48-b0be-401f-b18c-8ca89e9c0b6c/oauth2/v2.0/token \
--d 'client_id=5eb1de74-e449-4973-a620-52c4dc9157a9' \
--d 'scope=api://580b40b7-5513-4714-a4e0-8d4e784f7dc6/urn:taylordean:books:books_add' \
--d 'code=0.AXAASC…zZUzKYm18yM_5-SXz1uvRbbGYF7F32hE9zIQFRQY35haD' \
--d 'redirect_uri=https://localhost:9000' \
--d 'grant_type=authorization_code' \
--d 'state=111' \
--d 'client_secret=l4Q8Q~4WKiRXYSQZly5E6Ess.fKf__U1yJR3IaMd'
-
    - -
    -
    -
    -
    5. -
  5. -

    Once you receive the access token, you can test invoking the resource using the OpenAPI console in Choreo by specifying the scope.

    -
    6. -
- - - - - - -
-
- - -
- - - -
- - -
- - - -
-
-
- - - - - - - - - - - - - - - - - \ No newline at end of file diff --git a/en/site/authentication-and-authorization/secure-communication-between-the-choreo-gateway-and-your-backend-with-mutual-tls/index.html b/en/site/authentication-and-authorization/secure-communication-between-the-choreo-gateway-and-your-backend-with-mutual-tls/index.html deleted file mode 100644 index c43bf7f3b..000000000 --- a/en/site/authentication-and-authorization/secure-communication-between-the-choreo-gateway-and-your-backend-with-mutual-tls/index.html +++ /dev/null @@ -1,3336 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - Secure Communication Between the Choreo Gateway and Your Backend with Mutual TLS - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- - - -
- - - - - - -
- - -
- -
- - - - - - - -
-
- - - -
-
-
- - - - -
-
-
- - - -
-
-
- - - -
-
-
- - - -
-
- - - - - - - - - - - - - - - - - - - - -

Secure Communication Between the Choreo Gateway and Your Backend with Mutual TLS

-

To establish secure communication between the Choreo Gateway and your backend, you can configure mutual TLS.

-

Mutual TLS authentication involves both the client and server validating each other’s certificates before establishing a connection. The following diagram depicts this scenario:

-

Mutual TLS authentication

-

Configure mutual TLS to establish secure connectivity

-

To establish secure connectivity between the Choreo Gateway and your backend using mutual TLS, you must add the certificate of the backend (server certificate) to Choreo and add the certificate of Choreo (client certificate) as a trusted certificate in the backend.

-

Step 1: Configure the backend certificate

-

Prerequisites

-
    -
  • The endpoint must be protected with TLS.
    • -
  • The public certificate of the backend server should be extracted in PEM format and saved on the disk with the .pem extension.
    • -
-

To configure the backend certificate, follow the steps given below:

-
    -
  1. Sign in to the Choreo Console.
    2. -
  2. In the Component Listing pane, click on the API proxy for which you want to configure TLS. For instructions on how to create an API proxy component, see Develop an API Proxy: Step 1.
    3. -
  3. In the left navigation menu, click Develop and then click Endpoints.
    4. -
  4. On the Endpoints page, click Configure corresponding to the endpoint.
    5. -
  5. Click Upload Endpoint Certificate, and select the certificate file that you extracted in the prerequisites section to add it. This adds the certificate to all the environments as the default certificate for the endpoint. You can override this certificate if necessary when you deploy or promote the API.
    6. -
-

Step 2: Configure mutual TLS with the backend service

-

There are two approaches you can take to configure mutual TLS.

-
    -
  • Generate a key pair with a self-signed certificate from Choreo, download the public certificate, and subsequently add and configure it in the backend.
    • -
  • Upload your own public or private certificate pair to Choreo. Subsequently, add and configure the public certificate of this key pair in your backend.
    • -
-

Follow the step-by-step instructions below depending on how you want to establish mutual TLS with the backend service:

-
-
-
-

When you follow these steps, Choreo generates a key pair with a self-signed certificate. You can attach this key pair to any API proxy created within the same project.

-
    -
  1. Sign in to the Choreo Console.
    2. -
  2. In the Component Listing pane, click on the API proxy for which you want to generate a key pair. For instructions on how to create an API proxy component, see Develop an API Proxy: Step 1.
    3. -
  3. In the left navigation menu, click Develop and then click Endpoints.
    4. -
  4. On the Endpoints page, click Configure corresponding to the endpoint.
    5. -
  5. If your backend does not use a CA-signed certificate and you have not already added the backend certificate, click Upload Endpoint Certificate and add the backend certificate.
    6. -
  6. To enable mutual SSL, turn on the Mutual SSL toggle.
    7. -
  7. Click Add Client Certificate.
    8. -
  8. -

    In the Add Client Certificate Pair dialog, select Generate new key pair and specify a value as the common name for the certificate pair. This value will be used to identify the certificate.

    -

    Generate new key pair

    -
    9. -
  9. -

    Optionally, click Show advanced options to expand the section and specify appropriate values for each of the fields.

    -
    10. -
  10. Click Generate. This generates the certificate and lists it under Existing Certificates.
    11. -
  11. -

    Click the more options icon corresponding to the certificate and then click View and Download.

    -

    View and download certificate

    -

    This opens the certificate for you to view and download.

    -

    Certificate details

    -
    12. -
  12. -

    To download the certificate in PEM format, click Download. You can add this certificate as a trusted certificate in the API backend server.

    -
    13. -
-

Now you can associate the certificate with the API and deploy the API.

-
-
-

Here, you can use your own public certificate and private certificate as client certificates.

-
    -
  1. Sign in to the Choreo Console.
    2. -
  2. In the Component Listing pane, click on the API proxy for which you want to generate a key pair. For instructions on how to create an API proxy component, see Develop an API Proxy: Step 1.
    3. -
  3. In the left navigation menu, click Develop and then click Endpoints.
    4. -
  4. On the Endpoints page, click Configure corresponding to the endpoint.
    5. -
  5. If your backend does not use a CA-signed certificate and you have not already added the backend certificate, click Upload Endpoint Certificate and add the backend certificate.
    6. -
  6. To enable mutual SSL, turn on the Mutual SSL toggle.
    7. -
  7. Click Add Client Certificate.
    8. -
  8. -

    In the Add Client Certificate Pair dialog, select Use my own key pair.

    -

    Use own key pair

    -
    9. -
  9. -

    Upload the private key and public certificate in PEM format or copy and paste the content of the private key and public certificate.

    -
    10. -
  10. Click Add. This generates the certificate and lists it under Existing Certificates.
    11. -
  11. -

    Click the more options icon corresponding to the certificate and then click View and Download.

    -

    View and download certificate

    -

    This opens the certificate for you to view and download.

    -

    Certificate details

    -
    12. -
  12. -

    To download the certificate in PEM format, click Download. You can add this certificate as a trusted certificate in the API backend server.

    -
    13. -
-

Now you can associate the certificate with the API and deploy the API.

-
-
-
-

Step 3: Associate the certificate with the API

-

To associate a certificate with the API, follow the steps given below:

-
    -
  1. On the Endpoints page, go to the Existing Certificates section.
    2. -
  2. -

    Select the certificate you want to associate with the API.

    -

    Associate certificate

    -
    3. -
  3. -

    Click Save.

    -
    4. -
-

Step 4: Deploy the API

-

To deploy the API, follow the steps given below:

-
    -
  1. In the left navigation menu, click Deploy.
    2. -
  2. In the Build Area card, click Configure & Deploy.
    3. -
  3. Once the mediation application generation phase is complete, verify the endpoint URL populated for the environment and then click Save & Deploy.
    4. -
-

Once the deployment is complete, you can test the API.

-

Change the certificate for the production environment

-

If the API backend changes depending on the environment, the respective certificate must be updated for each environment.

-

Here, let's take a look at the steps to update the certificate for the production environment:

-
    -
  1. On the Deploy page, go to the Development card and click Promote.
    2. -
  2. In the Configurations pane that opens, click Endpoint Configuration. You will see all applicable certificates listed in the Mutual TLS list.
    3. -
  3. Select the certificate applicable to the production environment and click Promote. This promotes the component to the production environment with the selected certificate.
    4. -
- - - - - - -
-
- - -
- - - -
- - -
- - - -
-
-
- - - - - - - - - - - - - - - - - \ No newline at end of file diff --git a/en/site/authentication-and-authorization/secure-communication-between-the-choreo-gateway-and-your-backend/index.html b/en/site/authentication-and-authorization/secure-communication-between-the-choreo-gateway-and-your-backend/index.html deleted file mode 100644 index 321ae8df2..000000000 --- a/en/site/authentication-and-authorization/secure-communication-between-the-choreo-gateway-and-your-backend/index.html +++ /dev/null @@ -1,15 +0,0 @@ - - - - - - Redirecting... - - - - - - -Redirecting... - - diff --git a/en/site/authentication-and-authorization/secure-web-applications-with-managed-authentication/index.html b/en/site/authentication-and-authorization/secure-web-applications-with-managed-authentication/index.html deleted file mode 100644 index 5cc70db22..000000000 --- a/en/site/authentication-and-authorization/secure-web-applications-with-managed-authentication/index.html +++ /dev/null @@ -1,3574 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - Secure Web Applications with Managed Authentication - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- - - -
- - - - - - -
- - -
- -
- - - - - - - -
-
- - - -
-
-
- - - - -
-
-
- - - -
-
-
- - - -
-
-
- - - -
-
- - - - - - - - - - - - - - - - - - - - -

Secure Web Applications with Managed Authentication

-

The managed authentication capability of Choreo simplifies adding authentication and authorization to a single-page web application.

-

As a developer, you can easily set up Choreo's managed authentication to seamlessly integrate authentication into your web application. You just need to enable Choreo’s managed authentication, configure the built-in identity provider, and connect to Choreo without having to deal with the complexities of underlying OIDC/OAuth2.0 protocols.

-

Choreo's managed authentication follows the backend for frontend (BFF) architecture, which is a secure pattern recommended for browser-based applications that utilize OIDC/OAuth2.0 for authentication and authorization. This architecture ensures that OAuth tokens remain secure from browser-side code, making them immune to potential attacks like cross-site scripting (XSS).

-
-

Note

-

Choreo's managed authentication is currently available only for web applications created with React, Angular, or Vue.js buildpacks.

-
-
-

Warning

-

Managed authentication uses the 'SAMESITE' cookie attribute to prevent CSRF attacks. Therefore, it is recommended to use managed authentication with modern browsers that support the 'SAMESITE' attribute.

-
-

Step 1: Set up managed authentication for your web application

-

To secure your web application, you must implement authentication and authorization for it.

-

To easily set up authentication for your web application with Choreo's managed authentication, follow the steps given below. Before you move on to the next section, see Develop Web Applications Locally with Choreo’s Managed Authentication to ensure a seamless authentication experience when developing your web application on your local machine. You can also refer to the sample React app with managed authentication.

-

Step 1.1: Implement the sign-in functionality

-

To allow Choreo to manage the sign-in functionality for your web application, you must implement a sign-in button that redirects users to the /auth/login path on click. You can use the following code snippet or any custom button component from a preferred UI component library:

-
<button onClick={() => {window.location.href="/auth/login"}}>Login</button>
-
- -

This code snippet works as follows:

-

When a user clicks sign in on your web application, Choreo will redirect the user to the configured identity provider and handle the authentication process, conforming to the OICD/OAuth2.0 protocols. On successful sign-in, Choreo will set the relevant session cookies and redirect the user to the post-sign-in path (default is /). The user can then invoke any Choreo-deployed APIs depending on the permission granted.

-
-

Note

-

Refer to configure the identity provider section for details on configuring an identity provider for the web application.

-
-

Optional: Pass additional query parameters to the identity provider

-

If you want to pass additional query parameters to the identity provider, include them in the /auth/login request. Choreo appends these parameters to the authorize request sent to the identity provider.

-

For example,

-
<button onClick={() => {window.location.href="/auth/login?fidp=myfederatedidp"}}>Login</button>
-
- -

Step 1.2: Obtain user information claims

-

Choreo's managed authentication allows you to access user information claims that the identity provider returns post-sign-in, either via a cookie or by invoking a GET resource.

-

Obtain user information via the userinfo cookie

-

Upon successful sign-in, Choreo's managed authentication establishes a userinfo cookie that is accessible from the post-sign-in path you configured (by default, set to /). This userinfo cookie, provided by the identity provider, contains encoded user information claims.

-
-

Note

-
    -
  • The userinfo cookie is intentionally set to have a short lifespan of only 2 minutes.
    • -
  • As a developer, you can decide how to utilize the user information that you retrieve. You must securely store the user information because the stored information can also serve as a means to verify the logged-in state of a user.
    • -
  • The following example uses the js-cookie library for cookie parsing. You can use any cookie-parsing library of your choice. 
    • -
-
-

The recommended approach is to retrieve user information from the cookie and subsequently clear the cookie. The following is a sample code snippet that you can include in your post-sign-in path to retrieve user information from the cookie and subsequently clear the cookie:

-
    import Cookies from 'js-cookie';
-
-    // Read userinfo cookie value.
-    const encodedUserInfo = Cookies.get('userinfo')
-
-    // Decode the value. 
-    const userInfo = JSON.parse(atob(encodedUserInfo))
-
-    // Store the value in a preferred browser-based storage if needed.
-
-    // Clear the cookie.
-    Cookies.remove('userinfo', { path: <post-login-path> })
-
- -

Obtain user information via a GET endpoint

-

Choreo's managed authentication provides the GET endpoint /auth/userinfo in addition to the userinfo cookie that it sets after successful sign-in. You can use this endpoint to query information about users who have signed in. It also serves as a mechanism to check the state of a user who has signed in.

-

The following is an example of a request to this endpoint:

-
const response = await fetch('/auth/userinfo')
-
- -

If a user has signed in, the server sends a 200 OK response with the user information in JSON format in the response body. However, if the user is not signed in, the server sends a 401 Unauthorized response.

-

Step 1.3: Implement the sign-out functionality

-

To allow Choreo to manage the sign-out functionality of your web application, you can implement a sign-out button to redirect users to the /auth/logout path along with the session_hint cookie value on click. You can use the following code snippet or any custom button component from a preferred UI component library:

-
-

Note

-
    -
  • It is recommended to clear any user information (if stored) at the time of sign-out.
    • -
  • The following example uses the js-cookie library for cookie parsing. You can use any cookie-parsing library of your choice. 
    • -
-
-
<button onClick={async () => {
-    window.location.href = `/auth/logout?session_hint=${Cookies.get('session_hint')}`;
-}}>Logout</button>`
-
- -

When a user clicks the sign-out button, Choreo will clear the session cookies and redirect the users to the OIDC logout endpoint of the configured identity provider (if available).  

-

Step 1.4: Invoke APIs

-

To invoke Choreo APIs within the same organization as your web application, you can use the relative path /choreo-apis/<api-suffix>, regardless of whether managed authentication is enabled for the web application or not.

-
-

Note

-

To invoke a Choreo API from a web application, you need to create a Connection from the web application to the Choreo API.

-
-

For example, if the API URL is https://2d9ec1f6-2f04-4127-974f-0a3b20e97af5-dev.e1-us-east-azure.choreoapis.dev/rbln/item-service/api-e04/1.0.0, the <api-suffix> would be /rbln/item-service/api-e04/1.0.0. You can invoke the API using the /choreo-apis/rbln/item-service/api-e04/1.0.0 relative path from your single-page application.

-
-

Info

-

To copy the exact service URL of a Connection, you can follow the steps given below: - 1. In the Choreo Console, go to the appropriate web application component. - 2. In the left navigation menu, click Connections under Dependencies. - 3. Click on the required Connection and copy the service URL.

-
-

If you enable Choreo's managed authentication, you don't have to manually add any logic to attach an access token to the API call because Choreo APIs accept the cookies set by Choreo's managed authentication. You can directly invoke the API as follows:

-
    const response = await fetch('/choreo-apis/<api-suffix>')
-
- -

If Choreo's managed authentication is disabled, you must ensure that your web application attaches a valid access token to the API call.

-

Step 1.5: Handle session expiry

-

When a user session exceeds the configured session expiry time, it automatically expires. A 401 Unauthorized response status code for a Choreo API request from a logged-in user indicates that the session may have expired, requiring the user to re-login.

-

To programmatically handle session expiry and automatically re-login upon receiving a 401 Unauthorized response from a Choreo API, you can encapsulate the request with re-login logic. The following sample code snippet shows how to wrap GET requests:

-
    export const performGet = async (url) => {
-        try {
-            // API call
-            return await fetch('/choreo-apis/<api-suffix>');
-        } catch (error) {
-            if (error instanceof HttpError && error.status === 401) {
-                // Re-login
-                window.location.href = "/auth/login";
-            } else {
-                throw error;
-            }
-        }
-    };
-
- -

Step 1.6: Set up a custom error page

-

You can set up Choreo's managed authentication to redirect to a customized error page within your web application by defining the error path in the configuration. In the event of an error during a redirection-based process, such as sign in or sign out, Choreo will automatically redirect the user to the designated custom error page.

-
-

Note

-

If you have not configured an error path, Choreo's managed authentication will use its default error page whenever an error occurs.

-
-

Choreo's managed authentication will include the following query parameters in the URL when redirecting to the custom error page:

- - - - - - - - - - - - - - - - - -
ParameterDescription
codeA short textual error code indicating the error
messageThe description of the error
-

Now have successfully implemented Choreo's managed authentication for your web application. The next step is to enable managed authentication for the component, and subsequently deploy it.

-

Step 2: Enable managed authentication and configure the paths

-

To ensure that your web application functions seamlessly with managed authentication, it is essential to enable managed authentication for your web application component within Choreo.

-

You can enable managed authentication for your web application component at the time you deploy the component.

-
-

Tip

-

Managed authentication is enabled by default when you create a web application using React, Angular, or Vue.js buildpacks.

-
-
    -
  1. Sign in to the Choreo Console. This opens the project home page.
    2. -
  2. In the Component Listing pane, click on the web application for which you want to enable managed authentication.
    3. -
  3. In the left navigation menu, click Deploy.
    4. -
  4. In the Set Up card, click Configure & Deploy.
    5. -
  5. Add the necessary configurations for your component if applicable and click Next.
    6. -
  6. Make sure Managed Authentication with Choreo toggle is enabled.
    7. -
  7. -

    Specify appropriate values for the following fields:

    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    FieldDescriptionDefault value
    Post Login PathThe relative path that the application will be redirected to on successful sign-in. In your code, you must implement the necessary logic to obtain signed-in user's information from the userinfo cookie set by managed authentication. See Obtain user information via the userinfo cookie section in Obtain user information claims./
    Post Logout PathThe relative path to which Choreo redirects you on successful sign-out./
    Error PathThe relative path to which Choreo redirects you when an error occurs during a redirection-based flow (i.e., sign in or sign out). See Set up a custom error page.Built-in error page
    Session Expiry TimeThe time in minutes after which the user session expires. For a seamless experience, the session expiry value should match the refresh token expiry time of the OIDC application in your identity provider.10080 Minutes (7 Days)
    Additional ScopesAll additional scopes required by the web application. The openid, profile, and email scopes are added by default together with the scopes required to invoke subscribed APIs.none
    -
    -

    Note

    -

    If you need to change these configurations after you deploy the component, you can click Authentication Settings on the Set Up card, make the necessary changes, and deploy the component once again.

    -
    -
    8. -
-

Step 3: Configure the identity provider for the web application

-

You can configure your web application to work with the Choreo built-in identity provider, Asgardeo, or any external identity provider which supports OIDC/OAuth2.0 .

-
-

Note

-

The identity provider configured in this step should contain the users for the web application.

-
-

Click the respective tab for details depending on which identity provider you need to configure:

-
-
-
-

Follow the steps given below to configure the built-in identity provider by generating authentication keys:

-
-

Note

-

Choreo built-in identity provider is configured by default. Therefore, this step is optional.

-
-
    -
  1. In the Choreo Console, go to the component for which you want to manage OAuth keys.
    2. -
  2. In the left navigation menu, click Settings.
    3. -
  3. Click the Authentication Keys tab and then click on the environment for which you want to generate keys.
    4. -
  4. In the Identity Provider list, select Choreo Built-In Identity Provider.
    5. -
  5. -

    Click Generate Secret.

    -
    -

    Note

    -

    If the Regenerate Secret button is shown instead of the Generate Secret button, it indicates that OAuth keys are already generated for the component for the selected environment.

    -
    -
    6. -
-
-

Tip

-

Refer to Configure a User Store with the Built-In Identity Provider for details on adding test users in Choreo built-in identity provider.

-
-
-

Tip

-

If you need to invoke APIs secured with role-based access control, you can test this within Choreo by creating roles for the application and mapping those roles to relevant permissions (scope) and user groups. For more information, see create roles and assign permissions and assign roles to user groups sections in Test Secure API Access with Choreo Built-In Security Token Service.

-
-
-
-

Step 3.1: Create and configure an OIDC/OAuth2.0 application in Asgardeo

-
    -
  1. Sign in to Asgardeo.
    2. -
  2. In the top navigation menu, click the Organization list and select your organization.
    3. -
  3. In the Asgardeo Console left navigation menu, click Applications.
    4. -
  4. Click + New Application.
    5. -
  5. Click Standard-Based Application.
    6. -
  6. Specify a name for the application and select OAuth2.0 OpenID Connect as the protocol.
    7. -
  7. Click Register.
    8. -
  8. -

    Click the Protocol tab and follow these steps:

    -
      -
    1. Select Code and Refresh Token as the Allowed grant types.
      2. -
    2. Specify the following as Authorized redirect URLs:
        -
      • [your-web-application-url]/auth/login/callback
        • -
      • [your-web-application-url]/auth/logout/callback
        • -
      -
      3. -
    3. Specify your web application URL under Allowed origins.
      4. -
    4. In the Access Token section, select JWT as the Token type.
      5. -
    5. -

      Click Update.

      -
      -

      Tip

      -

      If you need to invoke APIs secured with role-based access control, you must create roles in the application and map those roles to relevant permissions (scope). Then those roles should be assigned to user groups. For more information, see the Asgardeo API authorization guide.

      -
      -
      6. -
    6. -

      Copy the Client ID and Client Secret of the application. You will need to use these values in the next step to link the OIDC/OAuth2.0 application to your Choreo component.

      -
      7. -
    -
    9. -
-

Step 3.2: Link the OIDC/OAuth2.0 application to the Choreo web application component

-
    -
  1. In the Choreo Console, go to the component for which you want to manage OAuth keys.
    2. -
  2. In the left navigation menu, click Settings.
    3. -
  3. Click the Authentication Keys tab and then click on the environment for which you want to generate keys.
    4. -
  4. In the Identity Provider list, select Asgardeo - [your-org-name].
    5. -
  5. Paste the Client ID and Client Secret of the OIDC/OAuth2.0 application you created in Asgardeo.
    6. -
  6. Click Add Keys.
    7. -
-
-
-

Step 3.1: Create and configure an OIDC/OAuth2.0 application in the external identity provider

-
    -
  1. Create an OIDC/OAuth2.0 application in your external identity provider.
    2. -
  2. -

    Configure the OIDC/OAuth2.0 application as follows:

    -
      -
    1. Set Code and Refresh Token as allowed grant types.
      2. -
    2. Add the following as authorized redirect URL.
      3. -
    3. Specify the following as authorized redirect URLs:
      4. -
    4. -

      Specify the access token type as JWT.

      -
      -

      Tip

      -

      If you want to invoke APIs secured with role-based access control, you must ensure that users are assigned a role mapping that grants the necessary permission for API invocation. The approach of mapping application roles to users can vary depending on the identity provider.

      -
      -
      5. -
    -
    3. -
-

Step 3.2: Link the OIDC/OAuth2.0 application to the Choreo component

-
    -
  1. In the Choreo Console, go to the component for which you want to manage OAuth keys.
    2. -
  2. In the left navigation menu, click Settings.
    3. -
  3. Click the Authentication Keys tab and then click on the environment for which you want to generate keys.
    4. -
  4. In the Identity Provider list, select your identity provider.
    5. -
  5. Paste the Client ID and Client Secret of the OIDC/OAuth2.0 application you created in your external identity provider.
    6. -
  6. Click Add Keys.
    7. -
-
-
-
- - - - - - -
-
- - -
- - - -
- - -
- - - -
-
-
- - - - - - - - - - - - - - - - - \ No newline at end of file diff --git a/en/site/authentication-and-authorization/test-secure-api-access-with-choreo-built-in-security-token-service/index.html b/en/site/authentication-and-authorization/test-secure-api-access-with-choreo-built-in-security-token-service/index.html deleted file mode 100644 index eeece1a33..000000000 --- a/en/site/authentication-and-authorization/test-secure-api-access-with-choreo-built-in-security-token-service/index.html +++ /dev/null @@ -1,3350 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - Test Secure API Access with Choreo Built-In Security Token Service - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- - - -
- - - - - - -
- - -
- -
- - - - - - - -
-
- - - -
-
-
- - - - -
-
-
- - - -
-
-
- - - -
-
-
- - - -
-
- - - - - - - - - - - - - - - - - - - - -

Test Secure API Access with Choreo Built-In Security Token Service

-

API security can protect APIs from potential threats and vulnerabilities, with authentication and authorization playing key roles. Authentication ensures that only authorized users or applications can access the API. This involves using API keys, tokens, or more advanced authentication methods like OAuth 2.0. Authorization governs the actions permitted for authenticated users or applications within the API. Authorization mechanisms restrict access to specific resources and actions based on user roles or permissions.

-

Choreo simplifies security testing for developers, allowing them to easily test APIs with permissions in non-critical environments. With its integrated security token service, Choreo provides authorization features that generate scopes based on the correlation between scopes, roles, and user groups. Developers can create roles, assign permissions, and set up user-group mappings using Choreo's built-in identity provider (IdP).

-

This guide walks you through the following steps to test the invocation of secured APIs with permissions using Choreo's built-in authorization capability:

-
    -
  • Assign scopes to an API in Choreo.
    • -
  • Create roles and assign permissions in Choreo.
    • -
  • Assign roles to user groups.
    • -
  • Test the API invocation.
      -
    • When Choreo manages the authentication (i.e., managed authentication enabled).
      • -
    • When the application independently handles the authentication (i.e., managed authentication disabled).
      • -
    -
    • -
-

Prerequisites

-

Before you try out this guide, ensure you have set up the following:

-
    -
  • Configure the Choreo built-in identity provider with users. For step-by-step instructions, see Configure a User Store with the Built-In Identity Provider.
    • -
  • Deploy and publish an API via Choreo. If you don't have an existing service in Choreo, you can either develop a service or an API Proxy.
    • -
  • A web application for API subscription. If you don't have an application in Choreo, you must create a web application
    • -
  • Administrator rights in your Choreo organization. You need this access to configure role-group and role-permission mappings.
    • -
-

Step 1: Assign permissions to an API in Choreo

-

You can provide fine-grained access control to your API resources with permissions. Follow the steps below to assign permissions to the resources in the API:

-
    -
  1. Go to https://console.choreo.dev/ and sign in.
    2. -
  2. In the Choreo Console top navigation menu, click the Project list and select the project that contains your component.
    3. -
  3. In the Component Listing pane, click on the component for which you want to attach permissions.
    4. -
  4. In the left navigation menu, click Deploy.
    5. -
  5. On the Deploy page, go to the Set Up card and click Endpoint Configurations. This opens the Endpoint Configurations pane.
    6. -
  6. Go to the Permissions List section and click + Add Permission(Scope).
    7. -
  7. In the Permissions List section, enter a permission value and click + Add New.
    8. -
  8. Click the copy icon in front of the added permission to copy the fully qualified name of it. Save this value for future reference.
    9. -
  9. To attach permissions to a resource, click the Select Permissions list under the respective resource and select the permissions you want to attach.
    10. -
  10. Click Apply.
    11. -
  11. -

    To apply the latest permissions to the deployed component, you must redeploy it. Follow the steps below to redeploy:

    -
      -
    1. Go to the Set Up card and click Configure & Deploy.
      2. -
    2. In the Configurations pane that opens, click Next. This opens the Endpoint Details pane.
      3. -
    3. Click Deploy.
      4. -
    -
    12. -
  12. -

    To publish your API to the Choreo Developer Portal, follow the steps given below:

    -
      -
    1. In the left navigation menu, click Manage and then click Lifecycle.
      2. -
    2. Click Publish.
      3. -
    -
    13. -
-

Step 2: Create roles and assign permissions

-

The permissions assigned to your API need to be associated with roles. Follow the steps below to create roles and assign permissions to the roles.

-
    -
  1. In the Choreo Console, go to the top navigation menu, click the Project list, and select the project that contains your component.
    2. -
  2. In the left navigation menu, click Settings.
    3. -
  3. Click the Application Security tab.
    4. -
  4. Click + Role.
    5. -
  5. Specify an appropriate Role Name and Role description.
    6. -
  6. -

    Select the permissions you want to assign to the role, and then click Create.

    -
    -

    Tip

    The permissions(scopes) defined for APIs exposed via components in the project and the permissions(scopes) required by connections created for components in the project are listed here.

    -

    -
    -
    7. -
-

Step 3: Assign roles to user groups

-

You must assign roles to the user groups defined in your Choreo built-in IdP to ensure that authenticated users can obtain access tokens with the required permissions.

-
    -
  1. In the Choreo Console, go to the top navigation menu, click the Organization list, and select the organization where you created your component.
    2. -
  2. -

    Click the Application Security tab and then click Role Management.

    -
    -

    Tip

    The roles defined within different projects in the organization are listed here.

    -

    -
    -
    3. -
  3. -

    Click Map Groups corresponding to a role that you want to assign to a group.

    -
    4. -
  4. Specify a group name and enter to add it. You can add multiple groups if necessary.
    5. -
  5. Click Save.
    6. -
-

Step 4: Test the API invocation

-

To test an API invocation, you must first create a connection to your API. To do this, you must have a web application created. You can use the web application you created while setting up the prerequisites.

-

To create a connection to the web application, follow the steps given below:

-
    -
  1. In the Choreo Console, go to the top navigation menu, click the Project list, and select the project where you created the web application.
    2. -
  2. On the project home page, click the web application listed under Component Listing.
    3. -
  3. In the left navigation menu, click Dependencies and then click Connections.
    4. -
  4. Create a connection to the API you deployed in Step 1.
    5. -
-

Now you can proceed to deploy the web application.

-

When deploying, if your web application is a single-page application (SPA), you have the option to allow Choreo to handle authentication on behalf of the application. This approach eliminates the need to incorporate OAuth protocol-specific logic into your application.

-

Test the invocation when Choreo-managed authentication is enabled

-

If managed authentication is enabled for your web application, Choreo automatically handles obtaining the necessary permission for API invocation. This occurs during the request for access tokens, allowing you to seamlessly invoke the subscribed APIs through your web application without additional intervention.

-
-

Note

-

If you change the permissions of an existing connection or create a new connection with permissions, you must redeploy your web application to ensure proper API invocation with managed authentication.

-
-

Test the invocation when the application manages the authentication

-

If your application manages authentication independently, follow the steps below to generate the necessary OAuth credentials to obtain access tokens:

-
    -
  1. In the left navigation menu, click Settings. This opens the settings of the web application component.
    2. -
  2. Click the Authentication Keys tab.
    3. -
  3. Click on an environment tab depending on the environment for which you want to generate credentials.
    4. -
  4. Select Choreo Built-In Identity Provider as the identity provider.
    5. -
  5. Click to expand Advanced Configurations and make sure the code and refresh grant types are selected. This is required to obtain access tokens with an authorization code grant.
    6. -
  6. Configure the callback URL of the web application to receive the authorization code.
    7. -
  7. Click Update Configurations.
    8. -
  8. Click Regenerate Secret and make a note of the client ID and secret that is generated.
    9. -
  9. Retrieve an access token using the authorization code grant, specifying the necessary OAuth scopes (You can see the endpoint details on the right side).
      -
    • When prompted for authentication, enter the credentials of a user within the built-in identity provider (IdP) who possesses the required assigned groups.
      • -
    • Navigate through the OAuth flow to obtain the JWT access token.
      • -
    -
    10. -
  10. Invoke the subscribed API using the access token.
    11. -
- - - - - - -
-
- - -
- - - -
- - -
- - - -
-
-
- - - - - - - - - - - - - - - - - \ No newline at end of file diff --git a/en/site/choreo-cli/choreo-cli-overview/index.html b/en/site/choreo-cli/choreo-cli-overview/index.html deleted file mode 100644 index 89a52d931..000000000 --- a/en/site/choreo-cli/choreo-cli-overview/index.html +++ /dev/null @@ -1,3170 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - Choreo CLI Overview - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- - - -
- - - - - - -
- - -
- -
- - - - - - - -
-
- - - -
-
-
- - - - -
-
-
- - - -
-
-
- - - -
-
-
- - - -
-
- - - - - - - - - - - - - - - - - - - - -

Choreo Command Line Interface (CLI) Overview

-

The Choreo Command Line Interface (CLI) is a command-line tool that helps you easily work with Choreo using commands. By utilizing commands, it significantly improves the development experience for Choreo users. This versatile tool simplifies different stages of the development process, making interactions more efficient and user-friendly.

-

Choreo serves as a comprehensive internal platform-as-a-service. The Choreo CLI serves as a pivotal tool aimed at enhancing its capabilities. With the Choreo CLI, you can leverage the following benefits:

-
    -
  • -

    Streamline Deployment Processes: Choreo CLI simplifies the entire process from creating a component in Choreo, building it, to deploying, testing, and monitoring independent of the language and framework used to implement the component.

    -
    • -
  • -

    Versatile workflow across frameworks: Regardless of your chosen framework, Choreo CLI offers a uniform end-to-end process. Choreo seamlessly integrates with different web application types (SPA, SSR, SSG, or simple static files), services (REST, GraphQL, gRPC), scheduled jobs, manual triggers, API proxies, and more. This versatility enables you to orchestrate a wide range of cloud-native components seamlessly.

    -
    • -
-

Key features of the Choreo CLI

-
    -
  • -

    Create and Manage Resources: Simplify project and component management. You can easily initiate and organize projects in Choreo through simple commands.

    -
    • -
  • -

    Create Builds and Deployments: Simplifies the process of creating builds and deploying components. You can build and promote components to environments easily with simple commands, ensuring a seamless transition from development to deployment.

    -
    -

    Note

    -

    The Choreo CLI currently supports the following component types:

    -
      -
    • Service
      • -
    • Web Application
      • -
    • Webhook
      • -
    • Scheduled Task
      • -
    • Manual Task
      • -
    -
    -
    • -
  • -

    Monitor with Logs : The integrated log functionality in the Choreo CLI allows you to effectively monitor your components. You can access valuable insights into your components behavior and performance directly from the command line.

    -
    • -
-

For troubleshooting tips and answers to frequently asked questions, see the Choreo CLI FAQ.

- - - - - - -
-
- - -
- - - -
- - -
- - - -
-
-
- - - - - - - - - - - - - - - - - \ No newline at end of file diff --git a/en/site/choreo-cli/get-started-with-the-choreo-cli/index.html b/en/site/choreo-cli/get-started-with-the-choreo-cli/index.html deleted file mode 100644 index e8153eb0f..000000000 --- a/en/site/choreo-cli/get-started-with-the-choreo-cli/index.html +++ /dev/null @@ -1,3529 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - Get Started with the Choreo CLI - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- - - -
- - - - - - -
- - -
- -
- - - - - - - -
-
- - - -
-
-
- - - - -
-
-
- - - -
-
-
- - - -
-
-
- - - -
-
- - - - - - - - - - - - - - - - - - - - -

Get Started with the Choreo CLI

-

This guide walks you through the following sample use case:

-
    -
  • Create a web application
    • -
  • Build the web application
    • -
  • Deploy the web application in the development environment
    • -
  • Promote the web application to the production environment
    • -
-

This guide utilized a simple to-do app built with Next.js and two basic environments: Development and Production.

-

Prerequisites

-

Follow the steps below to install the CLI:

-
    -
  1. -

    Install the Choreo CLI by running the command specific to your operating system:

    -
      -
    • -

      For Linux and Mac OS - 

      curl -o- https://cli.choreo.dev/install.sh | bash
-

      -
      • -
    • -

      For Windows (via PowerShell) - 

      iwr https://cli.choreo.dev/install.ps1 -useb | iex
-

      -
      • -
    -
    2. -
  2. -

    Verify the installation by running the following command:

    -
    choreo --version
-
    - -
    3. -
-

Step 1: Login to Choreo

-

Run the following command to login to Choreo:

-
choreo login
-
- -

Follow the instructions on the console to open the link in the browser and login to Choreo.

-

Step 2: Create a project

-

A project in Choreo is a logical group of related components that typically represent a single cloud-native application. A project consists of one or more components.

-

Create a multi-repository project named ‘web-app-project’ by running the following command:

-
choreo create project web-app-project --type=multi-repository
-
- -

Step 3: Create a Web Application component

-

In Choreo, a component within your project represents a singular unit of work in a cloud-native application. It can be a microservice, API, web application, or job/task. Each component is associated with a directory path in a Git repository containing the source code for the program.

-
-

Note

The Choreo CLI currently supports the following component types:

-
    -
  • Service
    • -
  • Web Application
    • -
  • Webhook
    • -
  • Scheduled Task
    • -
  • Manual Task
    • -
-

-
-
    -
  1. -

    Fork the repository https://github.com/wso2/choreo-sample-todo-list-app. This contains a sample web application that you can use for this guide.

    -
    2. -
  2. -

    To initiate the creation of a Web Application component within your project, use the following command: -This triggers a wizard prompting you to provide details for your Git repository and other configurations for your component.

    -
    choreo create component my-web-app --project=web-app-project --type=webApp
-
    - -
    3. -
  3. -

    Select the option Enter remote repository URL manually.

    -
    4. -
  4. -

    Enter the following values for the prompts.

    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    Promptvalue
    Configure source repositoryEnter remote repository URL manually
    Remote repository URLYour forked repository
    Branchmain
    Directory.
    Build-packnodejs
    Language Version20.x.x
    Port8080
    -
    -

    Note

    -

    The prompts may vary based on the type of component and the chosen build pack.

    -
    -
    5. -
-

Step 4: View component details

-

To view comprehensive information about the component, including basic details and service endpoint URLs once the services are deployed, you can use the following command:

-
choreo describe component "my-web-app" --project="web-app-project"
-
- -

Step 5: Build the component

-

You must build the components before deploying them to a specific environment. Execute the following command to trigger the build:

-
choreo create build "my-web-app" --project="web-app-project"
-
- -

Step 5.1: View build status

-

To check the status of a specific build, run the following command, replacing with the actual build ID obtained from the previous command:

-
-

Note

-

Typically, a build takes approximately 2 to 5 minutes to complete.

-
-
choreo describe build <build-id> --project="web-app-project" --component="my-web-app"
-
- -

Step 5.2: View build logs

-

Once the build is complete, you can view the build logs for verification or debugging purposes. In the unlikely case, the build encounters any issues, the logs will help you troubleshoot.

-
choreo logs --type=build --project="web-app-project" --component="my-web-app" --deployment-track="main" --build-id=<build_id>
-
- -

Step 6: Deploy to the Development environment

-

Once the build status indicates successful you can deploy the component in the Development environment by running the following command:

-
choreo create deployment "my-web-app" --env=Development --project="web-app-project" --build-id=<build-id>
-
- -

Step 6.1: Verify the deployment in the Development environment

-

After deploying the component, you can retrieve the URL of the deployed web application and open the publicly available web page to verify its behavior. Use the following command to retrieve the URL:

-
choreo describe component "my-web-app" --project="web-app-project"
-
- -

Step 6.2: View runtime logs

-

To observe runtime application logs of the web application in the Development environment, execute the following command:

-
choreo logs --type component-application --component my-web-app --project web-app-project --env Development --follow
-
- -

Step 7: Deploy to the Production environment

-

Once you verify your application in the Development environment, you can proceed to deploy it to the Production environment with the following command:

-
    -
  • Be sure to substitute with the id obtained after triggering the build.
    • -
-
choreo create deployment "my-web-app" --env=Production --project="web-app-project" --build-id=<build-id>
-
- -

Step 7.1: Verify the deployment in the Production environment

-

To ensure a successful deployment to the Production environment, retrieve the URL of the deployed web application using the following command:

-
choreo describe component "my-web-app" --project="web-app-project"
-
- -

Congratulations! You successfully deployed your web application in Choreo using the Choreo CLI.

-

View all CLI functions

-

Discover other functionalities of Choreo by running the following command.

-
choreo --help
-
- - - - - - -
-
- - -
- - - -
- - -
- - - -
-
-
- - - - - - - - - - - - - - - - - \ No newline at end of file diff --git a/en/site/choreo-concepts/choreo-marketplace/index.html b/en/site/choreo-concepts/choreo-marketplace/index.html deleted file mode 100644 index 8dcb710bb..000000000 --- a/en/site/choreo-concepts/choreo-marketplace/index.html +++ /dev/null @@ -1,3341 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - Choreo Marketplace - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- - - -
- - - - - - -
- - -
- -
- - - - - - - -
-
- - - -
-
-
- - - - -
-
-
- - - -
-
-
- - - -
-
-
- - - -
-
- - - - - - - - - - - - - - - - - - - - -

Choreo Marketplace

-

The Choreo Marketplace promotes and facilitates reusing and sharing services. It allows you to share all the services deployed in Choreo. -You can easily browse and search available services within the Marketplace and refer to the service definitions, documentation, instructions on how you can use it, etc.

-

Internal Marketplace

-

Discover services

-

The Marketplace includes all services deployed in your organization. This may be a large number of services. Therefore, effective discoverability is desirable.

-

You can use the search or apply various filter criteria to explore the services available.

- -

The top search bar provides universal searching to find the services. It allows you to search for a text in the following search attributes:

-
    -
  • Name: The service name.
    • -
  • Label: The service labels.
    • -
  • Content: The service content: overview, summary, and documentation.
    • -
  • All: All of the above criteria.
    • -
-

Filter

-

The Choreo Marketplace provides a filtering capability through the left-hand side filter panel. It allows you to filter with the following filter attributes:

-
    -
  • -

    Type: This filter enables you to categorize services based on their type, with two available options: "Internal" and "Third-party". "Internal" refers to services deployed within Choreo, while "Third-party" refers to services running externally to Choreo, independently added to the Marketplace.

    -
    • -
  • -

    Network Visibility: This filter enables you to categorize services based on their network visibility level, with three choices: "Public," "Organization," and "Project". "Public" filters services exposed publicly, "Organization" represents services exposed across the entire organization, and "Project" represents services exposed at the project level.

    -
    • -
-

Explore a service

-

You can click on the service card to open the detailed view of the service. The detailed service page features the service name, summary, version, labels, and service icon as the header.

-

Choreo organizes the service content into four tabs. The four tabs contain information as follows:

-
    -
  • -

    Overview: Choreo displays the service overview provided by the service developer. If the service developer has not provided any content at service creation, this section will be disabled. The service developer can provide the overview content via the Manage → Marketplace section of the component.

    -
    • -
  • -

    API definition: Includes the service's API definition, extracted from the user repository using the component-config file or endpoints.yaml file. -If the user does not specify an API definition, this tab remains empty.

    -
    • -
  • -

    How to use: Includes instructions on how to use the selected service. This includes instructions on creating a connection.

    -
    • -
  • -

    Related documents: Includes any additional content the user has provided as documents through the Manage -> Marketplace section of the component.

    -
    • -
-

Add a service to the Choreo Marketplace

-

You can add services to the Marketplace as Choreo services as follows:

-

Add a Choreo service

-

In Choreo, a service exposed through the platform is termed a Choreo service, with each service being identifiable by an endpoint within a Choreo service component. The Marketplace showcases a service for each endpoint within a service component.

-

Upon deployment to the initial environment, services get automatically added to the Marketplace. Choreo effortlessly collects essential details such as component name, endpoint name, description, and service definitions during this deployment, utilizing them to generate the corresponding service entries in the Marketplace.

-

The service name follows the convention of component name - endpoint name, while all other details remain unchanged.

-

Service versioning in the Choreo Marketplace

-

In the Choreo Marketplace, service versions are displayed in their major version format. Each service in the Choreo Marketplace represents the latest version of the service within its major version, following semantic versioning principles.

-

For example, if a Choreo service has versions v1.0, v1.1, v1.2, and v2.0, the Choreo Marketplace displays services with versions v1 and v2 representing the latest versions v1.2 and v2.0 respectively.

-

When you deploy a new minor version of a service already deployed in Choreo, the corresponding service in the marketplace automatically updates to reflect the latest version within the same major version.

-

Semantic-version-based intelligent routing in the Choreo Marketplace

-

When you use a service from the Choreo marketplace as a dependency, the dependent service's traffic automatically routes to the latest version of the corresponding service within the same major version. This ensures that your dependencies remain up-to-date without requiring manual updates within a major version.

-

For example, if you create a connection to connect your Choreo component named Foo to a Choreo service named Bar, which is currently available in the Choreo Marketplace as version v1, and if the latest version of the service Bar within the v1 range is v1.2, the component Foo will automatically connect to Bar v1.2. Subsequently, when Bar releases version v1.3, traffic from Foo will automatically route to Bar v1.3.

-

Edit services in the Choreo Marketplace

-

You can edit services in the Choreo Marketplace. During redeployment to any environment, Choreo automatically updates service definitions, visibility, and descriptions.

- - - - - - -
-
- - -
- - - -
- - -
- - - -
-
-
- - - - - - - - - - - - - - - - - \ No newline at end of file diff --git a/en/site/choreo-concepts/ci-cd/index.html b/en/site/choreo-concepts/ci-cd/index.html deleted file mode 100644 index 515c02071..000000000 --- a/en/site/choreo-concepts/ci-cd/index.html +++ /dev/null @@ -1,3416 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - CI/CD - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- - - -
- - - - - - -
- - -
- -
- - - - - - - -
-
- - - -
-
-
- - - - -
-
-
- - - -
-
-
- - - -
-
-
- - - -
-
- - - - - - - - - - - - - - - - - - - - -

CI/CD

-

Choreo provides a streamlined continuous integration and continuous deployment(CI/CD) experience to deploy applications and services efficiently across multiple environments.

-

Choreo creates environments for each project, where all components within the project share the environments. An environment is an isolated deployment area with restricted network and resource access. Services deployed in one environment cannot communicate with services deployed in another.

-

The Choreo cloud data plane provides two default environments (i.e., development and production). However, if you are in a private data plane organization, you can customize and create multiple environments based on your requirements.

-

Choreo adopts a build once, deploy many strategy to manage components across multiple environments. An application is built only once (i.e., per commit if automatic build on commit is enabled or based on the selected commit during a manual build). Then it is promoted to subsequent environments. This allows testing changes in lower, non-production environments like development before promoting the build to production.

-

Choreo injects configurations and secrets that you maintain at the environment level into components at runtime. This ensures a strict separation of environment-specific configurations from source code. Although configurations can vary across environments, the code and the built container remain unchanged. Configurations and secrets include:

-
    -
  • Resource credentials to a database, cache, or other backing services.
    • -
  • Credentials to external cloud services such as Amazon S3 or external APIs.
    • -
-

All configurations and secrets are encrypted at rest and in transit and stored in a secure vault. In a private data plane organization, you can store configurations and secrets in your infrastructure.

-

Build

-

Choreo auto-generates build pipelines that may slightly differ depending on the component type you create. Generally, all build pipelines work as follows:

-
    -
  • Builds a container image either from the provided source code or from a given Dockerfile for a specific commit.
    • -
  • Runs security and vulnerability scans if applicable, depending on the component type.
    • -
  • Pushes the container image to a container registry. In the cloud data plane, Choreo pushes the image to a Choreo-managed registry. If it is a private data plane organization, Choreo pushes the image to a registry that you own.
    • -
  • Updates service endpoints and API specifications from the provided repository if applicable.
    • -
-

Repeatable builds

-

Choreo can replicate builds from an identical code version (Git commit). This means that multiple builds initiated from the same Git commit will generate Docker images with the same behavior.

-
-

Note

-

In the event of multiple builds from the same code version, Choreo preserves only the most recent version of the Docker image created from the particular code version.

-
-

Trigger a build

-

On the Build page, click Build Latest. If necessary you have the option to select a particular commit and build an image.

-

If you want to automatically trigger a build with each commit, you can enable Auto Build on Commit.

-

Build logs

-

You can view build logs for specific builds on the Build page.

-

To view details of a specific build, click View Details corresponding to the build.

-

Deployment

-

Once you build an image in Choreo, you can deploy it via the Deploy page. To deploy an image, you can follow one of the approaches given below:

-
    -
  • -

    Manually deploy: In the Deploy page, go to the Set Up card and click Deploy.

    -
    • -
  • -

    Automatically deploy on build: In the Deploy page, go to Set Up card and enable Auto Deploy on Build. This automatically initiates deployment upon the completion of an automatic build.

    -
    • -
-
-

Info

-

To enable Auto Deploy on Build, you must enable Auto Build on Commit. This is because automatic deployment is not necessary or useful in scenarios where automatic build is not enabled.

-
-
-

Note

-
    -
  • You must trigger the first build in a Ballerina component manually to ensure that Choreo applies the required configurations to the development environment. You can enable automatic builds subsequently.
    • -
  • Choreo automatically checks the configurable defined in your source code against the configurable values applied in an environment. Choreo requests the configurable values on deployment and promotion. If you have changed the configurables in your Ballerina component, auto-build pipelines can fail as a precaution to avoid a component crash at runtime due to missing configurables.
    • -
  • The configurable verifying capability is only available for Ballerina components. For Dockerfile-based components, ensure to manage and update the configurations and secrets in environments ahead of time. You must also ensure backward compatibility between at least one release if you change the configurations.
    • -
-
-

Set up area and initial deployment

-

In the deploy phase, Choreo uses a setup area to merge the Docker image with its environment-independent configurations. Choreo then deploys this composite to the environment. This is known as the initial deployment.

-

Immutable deployments

-

Once Choreo deploys a component with configurations, the configurations become immutable. Any subsequent change results in a new deployment.

-

Promote a component to a higher environment

-

Choreo builds a container once per GitHub commit and then promotes it to subsequent higher environments.

-

You can go to the Deploy page of a component and promote it manually across environments.

-

Configurations

-

Choreo allows you to define both environment-independent configurations and environment-specific configurations.

-

Environment-independent configurations

-

These configurations apply to all environments.

-

To change environment-independent configurations, go to the Deploy page of the component, make the necessary configuration changes via the Set Up card, and then trigger a new deployment to the initial environment. From there, you can proceed to promote the component to higher environments.

-

Environment-specific configurations

-

These configurations apply to a particular environment.

-

To change environment-specific configurations, go to the Deploy page of the component, make the necessary configuration changes via the specific environment card, and trigger a new deployment.

-

To learn more about managing these configurations, see Configuration Management.

-

Task execution

-

The information on the Execute page is only applicable to scheduled and manual task components.

-

To track and monitor executions associated with a deployed scheduled task or manual task, go to the left navigation menu and click Execute.

-

You can view current and historic execution details along with a quick snapshot of recent activity via the total count of executions within the last 30 days. For each execution, you can view vital details such as the unique execution ID, the time it was triggered, and relevant revision information. Furthermore, you can dive deeper into the details by clicking on a specific execution to access its associated logs. This information enhances transparency, troubleshooting capabilities, and overall execution management, allowing you to easily monitor and analyze workflows.

-

Zero-downtime deployments

-

Choreo performs rolling updates to ensure zero downtime between deployments and promotions.

-

A new build undergoes a health check before traffic is switched to it from the current build.

-

If you configure the necessary health checks for a component, it can prevent deploying and promoting unhealthy versions of a component.

- - - - - - -
-
- - -
- - - -
- - -
- - - -
-
-
- - - - - - - - - - - - - - - - - \ No newline at end of file diff --git a/en/site/choreo-concepts/component/index.html b/en/site/choreo-concepts/component/index.html deleted file mode 100644 index 1b8832578..000000000 --- a/en/site/choreo-concepts/component/index.html +++ /dev/null @@ -1,3092 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - Component - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- - - -
- - - - - - -
- - -
- -
- - - - - - - -
-
- - - -
-
-
- - - - -
-
-
- - - -
-
-
- - - -
-
-
- - - -
-
- - - - - - - - - - - - - - - - - - - - -

Component

-

A component within a project represents a single unit of work in a cloud native application. A component is usually a single microservice, API, or job/task. Each component in Choreo is attached to a given directory path in a Git repository which either contains program source code or a Dockerfile with build instructions. A component is Choreo’s unit of deployment. Each component maps to a single pod in the Kubernetes cluster (data plane) at deployment time. Therefore, you can deploy, manage, and scale each component in Choreo independently.

-

Choreo supports different component types for various use cases. These include component types such as services, API proxies, integrations, web applications, and so on. Each component type hosts unique features based on its characteristics. For example, a scheduled integration component can accept a cron expression as a configuration to schedule an integration job/task.

- - - - - - -
-
- - -
- - - -
- - -
- - - -
-
-
- - - - - - - - - - - - - - - - - \ No newline at end of file diff --git a/en/site/choreo-concepts/configuration-management/index.html b/en/site/choreo-concepts/configuration-management/index.html deleted file mode 100644 index 7d2e23452..000000000 --- a/en/site/choreo-concepts/configuration-management/index.html +++ /dev/null @@ -1,15 +0,0 @@ - - - - - - Redirecting... - - - - - - -Redirecting... - - diff --git a/en/site/choreo-concepts/connections/index.html b/en/site/choreo-concepts/connections/index.html deleted file mode 100644 index e84c25b4a..000000000 --- a/en/site/choreo-concepts/connections/index.html +++ /dev/null @@ -1,3163 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - Connections - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- - - -
- - - - - - -
- - -
- -
- - - - - - - -
-
- - - -
-
-
- - - - -
-
-
- - - -
-
-
- - - -
-
-
- - - -
-
- - - - - - - - - - - - - - - - - - - - -

Connections

-

Services can exist in two main forms: standalone and integrated. Connecting services is an integral part in creating integrated solutions. Choreo allows you to connect services using Connections.

-

Using Connections, you can integrate the service you intend to deploy on Choreo with other services on Choreo or external resources. Upon creating a connection to a service on Choreo, Choreo provides you a Connection ID along with a set of connection parameters. Thereafter, you have the capability to configure your service to establish a connection using this Connection ID and map connection parameters to environment variable names in your Choreo component. You can read these environment variable names in your service implementation to retrieve the values, to create a programmatic connection to the service you want to consume.

-

At runtime, Choreo dynamically injects values into the environment variables based on the configured mapping. This approach ensures that the connection parameter values and the service connection creation remain loosely coupled, providing developers with flexibility and ease of maintenance.

-

You can add Connections in different visibility levels: Project and Component. The visibility levels are described below:

-

Project Connections

-

Project Connections are Connections you create to connect to services within a particular project. The Connections can be used by any component within the project.

-

For example, if you want to share a third-party service like Twilio across the project for all the components within that project to reuse, you can create a project connection. Components can refer to Project Connections using the connection ID. -Project connections created to consume Choreo services under the OAuth security scheme will share the same OAuth application across the project. Any component reusing such a connection will use the same client ID and client secret.

-

Component Connections

-

Component Connections are Connections you define at the component level and used by only that component.

-

For example, create a component connection if you want to connect a legacy service to a given component. Components can refer to the Component Connection using the connection ID. -If your component consumes more than one Choreo service, the Component connections created to consume those Choreo services under the OAuth security scheme can share the same OAuth application by sharing the same client ID and secret between all such connections.

-

Learn how you can share and reuse services using connections in Choreo.

- - - - - - -
-
- - -
- - - -
- - -
- - - -
-
-
- - - - - - - - - - - - - - - - - \ No newline at end of file diff --git a/en/site/choreo-concepts/data-planes/index.html b/en/site/choreo-concepts/data-planes/index.html deleted file mode 100644 index 2dde459d2..000000000 --- a/en/site/choreo-concepts/data-planes/index.html +++ /dev/null @@ -1,3360 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - Data Planes - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- - - -
- - - - - - -
- - -
- -
- - - - - - - -
-
- - - -
-
-
- - - - -
-
-
- - - -
-
-
- - - -
-
-
- - - -
-
- - - - - - - - - - - - - - - - - - - - -

Data Planes

-

Choreo's architecture comprises two key components: the control plane and the data plane. The control plane handles essential tasks such as administering organizations, users, and projects. In addition, it also governs the entire journey of application development, from the initial stages of creation, progressing to deployment, including measures to enforce governance and the provision for observability. The Choreo control plane is a SaaS that manages all cloud data planes and private data planes. It caters to diverse user personas, including CIOs, architects, and developers, as well as DevOps, site reliability engineers, and platform engineers.

-

The data plane is the environment where user applications are deployed based on configurations set in the control plane. These applications can range from services and web applications to APIs, integrations, and scheduled tasks. The applications can be written in various programming languages, allowing for a polyglot approach. Importantly, all traffic related to the runtime of user applications is restricted to the Choreo data plane, ensuring strict containment of user data within its boundaries.

-

Choreo's architecture features two distinct data plane types: cloud data planes and private data planes. A cloud data plane utilizes a multi-tenanted infrastructure model for deploying user applications, creating a shared yet secure environment for application runtime. In contrast, a private data plane(PDP) provides dedicated infrastructure for a single organization to run its user applications. This ensures an added layer of privacy and control for organizations with specific requirements.

-

Choreo high-level view

-

Private data planes

-

Infrastructure

-

Choreo private data planes can be deployed with almost all major cloud providers, such as Azure, AWS, and GCP, and are also compatible with on-premises infrastructure.

-

The essential requirements for a private data plane include upstream-compatible Kubernetes clusters, a container registry, a key vault (secret store), and a logging service or log storage.

-

Private data plane architecture

-

System components

-

Setting up the Choreo PDP system involves using a Helm installation on the Kubernetes infrastructure. -The following software components are installed during the helm execution:

-
    -
  • Cilium CNI and service mesh.
    • -
  • Choreo API Gateways and related components.
    • -
  • Choreo PDP agent.
    • -
  • Observability and logging APIs, along with observability agents.
    • -
  • Flux controller.
    • -
-

All of these software components receive automatic updates, including security patches and bug fixes through the flux controller connected to the Choreo Update Management System.

-

Connectivity with the control plane

-

The private data plane requires communication with the Choreo control plane to manage various activities. All these communications are outbound from the private data plane, ensuring that there is no need to open any specific IP:Port from its perspective for these interactions. However, if an organization's network restricts all outbound traffic, it is necessary to permit outbound traffic to the public IP range of the Choreo control plane.

-

The following table outlines the inbound and outbound connections from a private data plane:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Data plane componentEndpointDirectionProtocol
Choreo PDP agentChoreo control plane (CP) (mizzen server)OutboundWSS
Kubernetes API serverOutbound (cluster internal)HTTPS, WS
APIM/local adaptorGlobal adaptorOutboundHTTPS
Azure Service Bus (CP)OutboundAMQP
APIM/EnforcerEvent hub (CP)OutboundAMQP
Choreo secret resolverCloud secret storeOutbound (VPC internal)HTTPS
Container registryContainer registry (public)InboundHTTPS
Container registryOutbound (VPC internal)HTTPS
Certificate managerAzure DNS serviceOutboundHTTPS
LetsEncryptOutboundHTTPS
Flux source controllerGitHubOutboundHTTPS
Flux Helm controllerChoreo container registryOutboundHTTPS
- -

All communication between the control plane and the private data plane is secured using TLS.

-

Observability architecture

-

The following diagram depicts the architecture overview of Choreo's in-data-plane log and observability in Azure PDP:

-

Observability architecture

-

The private data plane observability architecture is centered around a strong commitment to data privacy and compliance. This is achieved through a strategic decision to retain logs and observability data within the data planes itself. Key aspects of this architecture include:

-
    -
  • Data storage at source: Logs and observability data are stored within the data plane itself, enhancing security, simplifying access, and ensuring compliance.
    • -
  • Direct browser-to-data-plane interaction: The Choreo Console in the user's browser directly interacts with APIs in the data plane, reducing potential data routing complexities and ensuring a more secure, direct flow of information.
    • -
  • Reduced data exposure points: Fetching data directly from the data plane's APIs minimizes the number of data transfer points, effectively decreasing the chances of data exposure or interception.
    • -
  • Compliance with regulatory standards: The architecture supports data locality, aligning with global regulatory standards like GDPR and CCPA by keeping data in its original environment.
    • -
  • Improved performance and real-time insights: Direct interaction between the browser and data plane results in faster data retrieval, providing users with immediate insights.
    • -
  • User transparency and control: Users have a clear view of their data's location and access methods, alongside granular control over data access.
    • -
-

Security

-

The Choreo private data plane ensures extensive, production-grade security, ranging from infrastructure and architecture to zero-trust network security. All incoming traffic is protected by a firewall and must undergo authentication and authorization via the API Gateway. It also provides end-to-end network traffic encryption using Cilium transparent encryption, ensuring efficient data path encryption.

-

For details on the private data plane security levels supported in Choreo pricing plans, see Private Data Plane Security Levels.

-

Management models

-

Choreo supports the following management models for private data planes (PDPs), fostering collaboration between WSO2 and customers across diverse scenarios:

-
    -
  • WSO2 fully managed (infrastructure and PDP in WSO2 subscription) model
    • -
  • WSO2 fully managed (infrastructure and PDP in customer subscription) model
    • -
  • Customer self-managed (WSO2 provides installation script and updates) model
    • -
-

To explore each management model in detail so that you can make informed decisions depending on the supported cloud-based operations and security, see Private Data Plane Management Models.

- - - - - - -
-
- - -
- - - -
- - -
- - - -
-
-
- - - - - - - - - - - - - - - - - \ No newline at end of file diff --git a/en/site/choreo-concepts/deployment-tracks/index.html b/en/site/choreo-concepts/deployment-tracks/index.html deleted file mode 100644 index 0b7c176a8..000000000 --- a/en/site/choreo-concepts/deployment-tracks/index.html +++ /dev/null @@ -1,3239 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - Deployment Tracks - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- - - -
- - - - - - -
- - -
- -
- - - - - - - -
-
- - - -
-
-
- - - - -
-
-
- - - -
-
-
- - - -
-
-
- - - -
-
- - - - - - - - - - - - - - - - - - - - -

Deployment Tracks

-

Deployment Tracks in Choreo are structured pathways for simplified software component deployment. They act like advanced CI/CD pipelines, ensuring your components reach their destinations seamlessly, whether from source code or prebuilt images. They establish an organized and structured approach that minimizes the chances of errors and challenges that are typically associated with deployment workflows.

-

The significance of Deployment Tracks

-

Deployment Tracks offer practical solutions to enhance the API consumer experience by addressing two critical challenges:

-
    -
  • -

    Streamlined deployment: Deployment Tracks serve as well-designed routes for your software components, enhancing the organization and reliability of the deployment process, similar to a well-structured express route.

    -
    • -
  • -

    Efficient API versioning: Especially beneficial for managed APIs, Deployment Tracks provide a straightforward method for creating API versions that seamlessly interact with previous iterations. This simplified version management benefits both API creators and consumers alike.

    -
    • -
-

Streamlined deployments

-

For streamlined deployments, Choreo dissects two integral approaches that leverage Deployment Tracks: the comprehensive CI/CD integration and the focused CD-Only strategy.

-

CI/CD with Deployment Tracks

-

A deployment track is linked to a particular branch within a GitHub repository. This connection is useful for handling deployments to various environments. On Choreo's Deploy page, you can easily visualize the deployments to specific environments associated with your selected deployment track. Moreover, the deployment track has a functionality that initiates automatic deployments for the linked branch. When activated, merging a pull request (PR) triggers a deployment to the development environment.

-

Deployment tracks - source repo

-

CD-Only strategy with Deployment Tracks

-

If you're inclined to use your own Continuous Integration (CI) systems and want to harness the deployment track as a Continuous Deployment (CD) pipeline, you can seamlessly link deployment tracks to a container registry repository. This configuration empowers users to effortlessly deploy images sourced directly from the linked container registry repository.

-

Deployment tracks - container registry

-

Efficient API versioning

-

This section applies to only service components. When working with service components in Choreo, it is important to have an effective API versioning mechanism. Choreo follows a versioning mechanism based on Semantic Versioning (SemVer) but only includes the major version and minor version with the prefix v.

-

For example, v1.2.

-

You can follow the approach given below when you version APIs in Choreo:

-
    -
  • Increment the major version when you make incompatible API changes.
    • -
  • Increment the minor version when you add functionality in a backward-compatible manner.
    • -
-
-

What is Semantic Versioning?

-

Semantic Versioning (SemVer) is a specification that defines how to assign and increment version numbers for software products, including APIs. For more information, see Semantic Versioning specification.

-
-

One of the primary concerns when dealing with SaaS APIs is to minimize disruption for API consumers while continuously developing and deploying updates.

-

In compliance with SemVer, changes that don't introduce breaking or additive modifications to the API are categorized as patch updates. Hover, from the perspective of API consumers, these changes should ideally not disrupt their API clients. Typically, API consumers are most concerned with major API version alterations, but there might be instances where minor version changes are communicated to them.

-

Therefore, in the context of deployment tracks, API developers only need to specify the major and minor versions being delivered from a particular deployment track. This information is treated as the API version attribute of a deployment track. If the publisher requires versioning for internal tracking purposes, this can be accomplished in Git through the use of Git tags, on GitHub with GitHub releases, and so forth.

-

Deployment tracks - api versioning

- - - - - - -
-
- - -
- - - -
- - -
- - - -
-
-
- - - - - - - - - - - - - - - - - \ No newline at end of file diff --git a/en/site/choreo-concepts/endpoint/index.html b/en/site/choreo-concepts/endpoint/index.html deleted file mode 100644 index 5f263e5cb..000000000 --- a/en/site/choreo-concepts/endpoint/index.html +++ /dev/null @@ -1,3093 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - Endpoint - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- - - -
- - - - - - -
- - -
- -
- - - - - - - -
-
- - - -
-
-
- - - - -
-
-
- - - -
-
-
- - - -
-
-
- - - -
-
- - - - - - - - - - - - - - - - - - - - -

Endpoint

-

An Endpoint is a network-exposed function that resides within a component. In Choreo, service and integration components expose one or more endpoints. Each endpoint in a component can have a service contract (OpenAPI, GraphQL SDL) associated with it. This contract is used to expose the endpoint to consumers. In the absence of a contract, Choreo uses /* exposed on all HTTP verbs as the default contract to expose the service or the integration.

-

Each endpoint exposed in a component is considered a single API. Therefore, Choreo allows you to do API management per endpoint for a given component. For example, you can perform lifecycle management and configure security settings per endpoint in a given component.

-

See Configure Endpoints to learn how to configure endpoints when developing components in Choreo.

- - - - - - -
-
- - -
- - - -
- - -
- - - -
-
-
- - - - - - - - - - - - - - - - - \ No newline at end of file diff --git a/en/site/choreo-concepts/environments/index.html b/en/site/choreo-concepts/environments/index.html deleted file mode 100644 index 952668fb2..000000000 --- a/en/site/choreo-concepts/environments/index.html +++ /dev/null @@ -1,3094 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - Environments - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- - - -
- - - - - - -
- - -
- -
- - - - - - - -
-
- - - -
-
-
- - - - -
-
-
- - - -
-
-
- - - -
-
-
- - - -
-
- - - - - - - - - - - - - - - - - - - - -

Environments

-

Choreo offers developers one or more environments to run their applications within a given data plane. By default, the Choreo cloud data plane provides two environments (i.e., development and production). Each project in Choreo is associated with one or more environments available in the organization. For example, project A may choose to utilize dev, staging, and production environments, while project B may only use development and production environments.

-

You can promote components within a project across available environments. When you promote a component, its configuration values can be overridden with environment-specific values.

-

The following diagram illustrates how a component is promoted across environments.

-

Choreo environments

- - - - - - -
-
- - -
- - - -
- - -
- - - -
-
-
- - - - - - - - - - - - - - - - - \ No newline at end of file diff --git a/en/site/choreo-concepts/organization/index.html b/en/site/choreo-concepts/organization/index.html deleted file mode 100644 index 9088d445c..000000000 --- a/en/site/choreo-concepts/organization/index.html +++ /dev/null @@ -1,3281 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - Organization - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- - - -
- - - - - - -
- - -
- -
- - - - - - - -
-
- - - -
-
-
- - - - -
-
-
- - - -
-
-
- - - -
-
-
- - - -
-
- - - - - - - - - - - - - - - - - - - - -

Organization

-

An organization in Choreo is a logical grouping of users and user resources. A first-time user must create an organization and be a member of it when signing in to Choreo. Users and resources in an organization cannot access resources in another organization unless an admin of the other organization invites them and adds them as a member of that organization. A user cannot create more than one organization.

-

Switch organizations

-

If you are a member of more than one organization, you can switch from one organization to another when necessary. To do this, select the required organization from the Organization list in the Choreo Console header.

-

Inviting users

-

An organization administrator can invite users to the organization by assigning them specific groups. Invited users receive an invitation via email. An invited user must accept the invitation to join the organization and access the resources of that organization.

-

Manage user permission

-

Choreo manages user permissions with groups and roles.

-

Groups

-

A group in Choreo is a collection of users, each with one or more roles assigned to them. Users within a group inherit the permissions associated with the roles assigned to that group. For instance, if a user is added to the API Publisher group, they will automatically receive the API Publisher role.

-

Choreo comes with predefined groups already configured with specific roles, as follows:

-
    -
  • API Publisher: A collection of users who have the API Publisher role.
    • -
  • API Subscriber: A collection of users who have the API Subscriber role.
    • -
  • Admin : A collection of users who have the Admin role.
    • -
  • Billing Admin : A collection of users who have the Billing Admin role.
    • -
  • Choreo DevOps : A collection of users who have the Choreo DevOps role.
    • -
  • Developer : Users who develop, deploy, and manage cloud native applications at scale.
    • -
  • External API Subscriber: A collection of users who have the External API Subscriber role.
    • -
-

When creating a new group to invite members, be sure to assign a role to the group to ensure users have the required permissions.

-

Roles

-

Choreo roles are defined as follows:

-
    -
  • API Publisher: An API publisher can discover, create, publish, delete, test, and manage an API.
    • -
  • API Subscriber: An API subscriber is a developer in a particular organization. An API subscriber can subscribe to an application, manage subscriptions, manage applications, generate API keys, and manage API keys.
    • -
  • Admin: An administrator is responsible for all administration tasks, including user management, customizing the Developer Portal, managing projects, enabling analytics, managing domains, etc.
    • -
  • Billing Admin: Is responsible for billing administration that includes viewing tiers, creating and viewing organizations, managing invoices, viewing and creating subscriptions, and viewing and creating payment methods.
    • -
  • Choreo DevOps: A Choreo DevOps user is a user with access to the Choreo DevOps portal, enabling them to actively manage, ensure dependable deployment, and monitor components.
    • -
  • Developer : A user who can develop, deploy, and manage cloud native applications at scale.
    • -
  • External API subscriber: External API subscribers are API consumers who have access only to the API Developer Portal. They can join an organization with the sole purpose of consuming APIs.
    • -
  • Environment Manager (Deprecated): Manages deployment environments.
    • -
-

Organization ID

-

The Organization ID serves as a unique identifier for each organization. To get the organization ID, follow the steps below:

-
    -
  1. Go to https://console.choreo.dev/ and sign in. This opens the project home page.
    2. -
  2. Click on the Organization list on the header and select your organization.
    3. -
  3. In the left navigation, click Settings.
    4. -
  4. In the header, click the Organization list. This will open the organization level settings page.
    5. -
  5. Under Organization click Copy ID.
    6. -
-

Organization Handle

-

The organization handle is a unique string that directly corresponds to your organization's name. To get the organization handle, follow the steps below:

-
    -
  1. Go to https://console.choreo.dev/ and sign in. This opens the project home page.
    2. -
  2. Click on the Organization list on the header and select your organization.
    3. -
  3. In the left navigation, click Settings.
    4. -
  4. Under Organization click Copy Handle.
    5. -
- - - - - - -
-
- - -
- - - -
- - -
- - - -
-
-
- - - - - - - - - - - - - - - - - \ No newline at end of file diff --git a/en/site/choreo-concepts/project/index.html b/en/site/choreo-concepts/project/index.html deleted file mode 100644 index 1c00fe1a8..000000000 --- a/en/site/choreo-concepts/project/index.html +++ /dev/null @@ -1,3093 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - Project - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- - - -
- - - - - - -
- - -
- -
- - - - - - - -
-
- - - -
-
-
- - - - -
-
-
- - - -
-
-
- - - -
-
-
- - - -
-
- - - - - - - - - - - - - - - - - - - - -

Project

-

A project in Choreo is a logical group of related components that typically represent a single cloud native application. A project consists of one or more components. All components within a project can ideally be (but is not restricted to) in a single GitHub repository under different paths. This is also known as the monorepo architecture.

-

At deployment time, all components within a given project are deployed into a single namespace of the Kubernetes cluster. Components within a project can be exposed to the public internet, internally to the rest of the organization, or privately within the project only. A project in Choreo is represented as a cell with regard to the Cell-based architecture. The following diagram illustrates a project and how the components within a project are laid out at runtime:

-

Project

- - - - - - -
-
- - -
- - - -
- - -
- - - -
-
-
- - - - - - - - - - - - - - - - - \ No newline at end of file diff --git a/en/site/choreo-concepts/resource-hierarchy/index.html b/en/site/choreo-concepts/resource-hierarchy/index.html deleted file mode 100644 index d3ee40c86..000000000 --- a/en/site/choreo-concepts/resource-hierarchy/index.html +++ /dev/null @@ -1,3179 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - Resource Hierarchy - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- - - -
- - - - - - -
- - -
- -
- - - - - - - -
-
- - - -
-
-
- - - - -
-
-
- - - -
-
-
- - - -
-
-
- - - -
-
- - - - - - - - - - - - - - - - - - - - -

Resource Hierarchy

-

The following diagram depicts the high-level resources and their relationships in Choreo.

-

Resource hierarchy

-

Organizations and data planes

-

Data planes are connected to the organization and are available for all the projects in the organization. When you create an environment in a project, the data plane connected to the organization is linked with an automatically generated Kubernetes namespace.

-

Environments and data planes

-

Choreo allows multiple Kubernetes clusters to be associated with an environment.

-

This allows you to build highly resilient and resource-efficient solutions that utilize multiple clusters. Choreo synchronizes your applications and workloads between associated clusters in an environment. This allows you to perform multi-cluster deployment with a single click.

-

The following diagram depicts how multiple clusters associate with different environments:

-

Environments and dataplanes

-
-

Note

-

It is not necessary to use a different cluster per environment. You can create multiple environments on the same cluster. The above diagram is only an example of a specific solution. Your application architecture may require an entirely different configuration than what is depicted in the diagram.

-
-

Components and environments

-

Components belong to a project in Choreo and environments are provisioned per project as well. When a component is deployed, it is deployed as a container to the specified environment. Once deployed, you can promote the container image across the environments available in the project.

- - - - - - -
-
- - -
- - - -
- - -
- - - -
-
-
- - - - - - - - - - - - - - - - - \ No newline at end of file diff --git a/en/site/consume/developer-portal/index.html b/en/site/consume/developer-portal/index.html deleted file mode 100644 index 01f424356..000000000 --- a/en/site/consume/developer-portal/index.html +++ /dev/null @@ -1,15 +0,0 @@ - - - - - - Redirecting... - - - - - - -Redirecting... - - diff --git a/en/site/consume/manage-application/index.html b/en/site/consume/manage-application/index.html deleted file mode 100644 index c0c68be13..000000000 --- a/en/site/consume/manage-application/index.html +++ /dev/null @@ -1,15 +0,0 @@ - - - - - - Redirecting... - - - - - - -Redirecting... - - diff --git a/en/site/consume/manage-subscription/index.html b/en/site/consume/manage-subscription/index.html deleted file mode 100644 index 9b12fc49f..000000000 --- a/en/site/consume/manage-subscription/index.html +++ /dev/null @@ -1,15 +0,0 @@ - - - - - - Redirecting... - - - - - - -Redirecting... - - diff --git a/en/site/consume/test-api/index.html b/en/site/consume/test-api/index.html deleted file mode 100644 index 5c4fb5a46..000000000 --- a/en/site/consume/test-api/index.html +++ /dev/null @@ -1,15 +0,0 @@ - - - - - - Redirecting... - - - - - - -Redirecting... - - diff --git a/en/site/consuming-services/consuming-a-sevice/index.html b/en/site/consuming-services/consuming-a-sevice/index.html deleted file mode 100644 index 1023b4fbb..000000000 --- a/en/site/consuming-services/consuming-a-sevice/index.html +++ /dev/null @@ -1,3629 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - Consume a Service - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- - - -
- - - - - - -
- - -
- -
- - - - - - - -
-
- - - -
-
-
- - - - -
-
-
- - - -
-
-
- - - -
-
-
- - - -
-
- - - - - - - - - - - - - - - - - - - - -

Consume a Service

-

Choreo is a platform that allows you to create, deploy, and consume services seamlessly. The Choreo Developer Portal simplifies discovering and using APIs for API consumers.

-

Typically, an application developer who may be internal or external to your organization would want to consume the APIs published in the Developer Portal to develop their applications. In this guide, you will learn how to discover, generate credentials, and test the consumption of a service published in the Choreo Developer Portal. You will also learn how to invoke the service via a web application.

-

This guide walks you through the following steps:

-
    -
  • Create an application in the Developer Portal and generate credentials for the application.
    • -
  • Subscribe the API to the application.
    • -
  • Consume a published REST API via your web application.
    • -
-

Prerequisites

-

Before you try out this guide, if you do not have a published service that you would want to consume via the Developer Portal, follow Develop a Service documentation to publish and deploy a sample REST API.

-

Discover APIs

-

In the Choreo Developer Portal, developers can use the search option to find APIs by name. The APIs and services that are created and published through the Choreo Console become visible in the Developer Portal depending on the API's visibility as follows:

-
    -
  • -

    Public: The API is visible to all in the developer portal.

    -
    • -
  • -

    Private: The API is visible to the users who only sign in to the Developer Portal.

    -
    • -
  • -

    Restricted: The API is visible to only the user that has the roles that you specify. This option helps developers to enforce fine-grained access control to the API.

    -
    • -
-

To learn more about API visibility, see Control API Visibility.

-

The Choreo Developer Portal lists APIs based on their major version.

-

Developer Portal APIs

-

The overview page of an API displays the subscribed versions of the API along with the respective subscription details such as the subscribed application and the application creation date.

-

API overview

-
-

Tip

-

If you want to use an API, the recommended approach is to use the latest version of it. You can copy the major version pattern provided as the value of Endpoints(s) on the API overview page and use it in your client application. This ensures that your application always invokes the latest API version.

-
-

Create an application

-

An application in Choreo is a logical representation of a physical application such as a mobile app, web app, device, etc. To consume an API in Choreo, you need to create an application that maps to your physical application and then subscribes to the required API over a usage policy plan that gives you a usage quota. A single application can have multiple subscriptions to APIs. Using the consumer key and consumer secret, you can generate an access token that you can use to invoke all the APIs subscribed to the same application.

-

This section walks you through the steps to create an application in Choreo.

-

Let's get started!

-

Step 1: Create an application

-

To create an application in the Choreo Developer Portal, follow the steps given below:

-
    -
  1. Sign in to the Choreo Developer Portal.
    2. -
  2. Click Applications. and then click +Create.
    3. -
  3. Enter a name and description for the application.
    4. -
  4. Click Create.
    5. -
-

This creates the application and opens the application overview page. You can view details such as the token type, workflow status, and the application owner of the API.

-

Step 2: Generate keys

-

Choreo provides an OAuth 2.0 bearer token-based authentication for API access. An API access token/key is a string that is passed as an HTTP header of an API request to authenticate access to the API.

-

Once you create an application in Choreo, you can generate credentials for it. When you generate credentials for the first time, Choreo provides a consumer key and consumer secret for the application. The consumer key becomes the unique identifier of the application and is used to authenticate the application.

-

The following section walks you through the steps to generate an API access token in Choreo.

-

Generate environment-specific keys and tokens

-

You can generate keys and tokens to invoke production and non-production endpoints separately.

-
-

Note

-

The capability to access production endpoints depends on your role. If you have permission to access production endpoints, you can generate keys and tokens to invoke production endpoints.

-
-
    -
  1. In the Choreo Developer Portal header, click Applications.
    2. -
  2. On the My Applications page, click on the application for which you want to generate keys and tokens.
    3. -
  3. In the left navigation menu, click the required environment under Credentials. This opens the Application Keys pane of the specific environment.
    4. -
  4. -

    Click to expand Advanced Configurations and review the options.

    -
      -
    • Grant Types: Select the grant types to use when generating the access token.
      • -
    • Public Client: Select Allow authentication without the client secret if your application can be considered as a public client such as an application running on a browser or mobile device.
      • -
    • PKCE for enhanced security: Select Mandatory if you want the application to send a code challenge in the authorization request and the corresponding code verifier in the token request. Asgardeo supports SHA-256 and plain.
      • -
    • Application access token expiry time: Specify the access token expiry time in seconds.
      • -
    • Refresh token expiry time: Specify the refresh token expiry time in seconds.
      • -
    • ID token expiry time: Specify the ID token expiry time in seconds.
      • -
    -
    5. -
  5. -

    Click Generate Credentials. This opens the Application Keys pane with values populated for the credentials.

    -
    6. -
-

You can use this consumer key and consumer secret values to generate an API access token by invoking the token endpoint. You can also revoke the access token by invoking the revoke endpoint.

-

To generate a test token for testing purposes, you can click Generate Token and copy the test token that is displayed. Alternatively, click cURL and copy the generated cURL command to use via a cURL client and obtain a test token.

-
-

Warning

Make sure you do not use the test token in your production environment.

-

-
-

Subscribe to an API

-

You must subscribe to a published API to use it in your application. New API subscriptions cover all minor versions within the subscribed API’s major version.

-

The subscription process is designed to ensure the secure authentication of API requests via application keys. Alternatively, you can generate credentials for an API without an explicit subscription to an application. However, this approach limits the capability to control advanced configurations such as access token expiry time, revoke token expiry time, ID token expiry time, and enabling access to the API without a secret. Generating keys in the API is recommended for testing or short-term usage but not for long-term production usage.

-

To subscribe to an API via an application, follow the steps given below:

-
    -
  1. Sign in to the Choreo Developer Portal.
    2. -
  2. In the Developer Portal header, click Applications.
    3. -
  3. On the My Applications page, click on the application with which you want to subscribe to an API.
    4. -
  4. In the left navigation menu, click Subscriptions.
    5. -
  5. In the Subscription Management pane that opens, click + Add APIs.
    6. -
  6. -

    Click Add to subscribe to an API. Depending on your requirement, you can subscribe to one or more APIs.

    -
    -

    Tip

    -

    When a new minor version of an API is published, the major version-based invocation URL will automatically route to the latest minor version within the subscribed API's major version. This ensures that existing client applications can continue to function without disruption while benefiting from the improvements or additions in the newer minor version.

    -
    -

    Add APIs

    -

    Once you subscribe to an API, you can invoke the API using the application keys.

    -
    7. -
-

Consume the API via your web application

-

You can invoke the API/service using the credentials you created above. Since Choreo services are secured, you need to invoke the services securely with the help of your IdP. To invoke the API/service you created securely, you need to follow the steps below:

-
    -
  1. Create a web application in Choreo.
    2. -
  2. Create an OAuth application in the IdP.
    3. -
  3. Configure the web application to authenticate the API/service invocations from the IdP, and securely invoke the service/API in Choreo.
    4. -
  4. Deploy the web application.
    5. -
-

In this guide, you will be using the following products and examples:

- -

Step 1: Create a web application component

-
-

Info

-

You can use your own web application implementation in place of the sample web application. For this exercise, let's use the choreo-samples/reading-list-app/reading-list-front-end as the web application.

-
-

To host the front-end application in Choreo, you must create a web application component. To create a web application component, follow the steps given below.

-
    -
  1. In the Choreo console, select the project of the reading list application that you created in the previous steps, from the project list located on the header.
    2. -
  2. Click Create under the Component Listing section to create a new component.
    3. -
  3. On the Web Application card, click Create.
    4. -
  4. -

    Enter a unique name and a description for the web application. You can enter the name and description given below:

    - - - - - - - - - - - - - - - - - -
    FieldValue
    NameReading List Web App
    DescriptionFrontend application for the reading list service
    -
    5. -
  5. -

    Click Next.

    -
    6. -
  6. To allow Choreo to connect to your GitHub account, click Authorize with GitHub.
    7. -
  7. -

    In the Connect Repository pane, enter the following information:

    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    FieldDescription
    GitHub AccountYour account
    GitHub Repositorychoreo-samples
    Branchmain
    BuildpackClick React since the frontend is a React application built with Vite
    Build Context Pathreading-list-app/reading-list-front-end
    Build Commandnpm install && npm run build
    Build Outputdist
    Node Version18
    -
    8. -
  8. -

    Click Create. This initializes the service with the implementation from your GitHub repository and takes you to the Overview page of the component.

    -
    9. -
-

Let's consume the service through the web app. Choreo services are by default secured. To consume a service in Choreo you need an access token. Let's configure the web application to connect to an IdP (For this guide, let's use Asgardeo) to generate an access token for a user.

-

Step 2: Create an OAuth application in the IdP

-

To invoke the service/API in Choreo you require a token. To obtain a token you need to create an OAuth application in the IdP. If you use any other IdP other than Asgardeo, create an OAuth application and set the following:

-
    -
  • Allowed grant types: Code
    • -
  • Public client: Mark as a public client in an application.
    • -
  • Authorized redirect URLs: Enter the web app URL you copied earlier.
    • -
  • Allowed origins field: Add the same URLs that you added as authorized redirect URLs.
    • -
  • Access Token: Set JWT as the Token type.
    • -
-

Choreo uses Asgardeo as the default identity provider for Choreo applications. When you create an application in the Choreo Developer Portal, it automatically creates a corresponding application in Asgardeo. You can go to the Asgardeo application to specify the configurations required for end users to sign in to the front-end application. Follow the steps below to configure the Asgardeo OAuth application:

-
    -
  1. Access Asgardeo at https://console.asgardeo.io/ and sign in with the same credentials with which you signed in to Choreo.
    2. -
  2. Make sure you are in the same organization that you were when you created the application in the Choreo Developer Portal. You can click the Organization list in the Asgardeo Console top menu and ensure you are in the correct organization.
    3. -
  3. In the Asgardeo Console's left navigation, click Applications. You will see the readingListApp that Choreo automatically created for you.
    4. -
  4. Click on the edit icon to edit the application.
    5. -
  5. -

    Click the Protocol tab and apply the following changes:

    -
      -
    1. Under Allowed grant types, select Code.
      2. -
    2. Select the Public client checkbox.
      3. -
    3. In the Authorized redirect URLs field, enter the web app URL you copied earlier and click the + icon to add the entry.
      4. -
    4. In the Allowed origins field, add the same URLs that you added as authorized redirect URLs.
      5. -
    5. Under Access Token, select JWT as the Token type.
      6. -
    6. Click Update.
      7. -
    -
    6. -
-

Step 3: Configure the web application to connect to the IdP and invoke the service

-

In this step, you are adding the configurations needed for the web app to successfully invoke the Reading List Service REST API. These configurations need to be updated for each environment you deploy the web app. Here you will be updating the configurations for the development environment.

-
-

Note

The web application is reading the environment-specific configurations from the window object at runtime. This is done via the config.js file in the root of the web application. In this section, you will mount the config.js file for the development environment. You will need to do the same for other environments as well when you deploy your web application to multiple environments.

-

-
-

To configure the front-end application, follow the steps given below:

-
    -
  1. While on the web application component page, click DevOps in the left navigation menu and then click Configs and Secrets.
    2. -
  2. Click + Create.
    3. -
  3. -

    Select the mount configuration options as follows and click Next:

    - - - - - - - - - - - - - - - - - -
    FieldDescription
    Config TypeConfig Map
    Mount TypeFile Mount
    -
    4. -
  4. -

    Specify values as follows for the mount configuration:

    - - - - - - - - - - - - - - - - - -
    FieldDescription
    Config NameWeb App Config
    Mount Path/usr/share/nginx/html/config.js. Every config that needs to be exposed through the web server should be placed inside /usr/share/nginx/html/
    -
    5. -
  5. -

    Copy the config details as a JSON file as shown below into the text area. Fill the placeholders with the values you copied from the previous steps as mentioned in the table below:

    -
    window.config = {
-    redirectUrl: "<web-app-url>",
-    asgardeoClientId: "<asgardeo-client-id>",
-    asgardeoBaseUrl: "https://api.asgardeo.io/t/<your-org-name>",
-    choreoApiUrl: "<reading-list-service-url>"
-};
-
    - - - - - - - - - - - - - - - - - - - - - - - - - - -
    FieldDescription
    redirectUrlThe web app URL you copied earlier.
    asgardeoClientIdThe Client ID of your OAuth application. In Asgardeo, you can find it on the Protocol tab of the readingListApp application
    asgardeoBaseUrlSpecify the IdP API URL (For example, Asgardeo API URL) with your organization name. i.e., https://api.asgardeo.io/t/<ORG_NAME>.
    choreoApiUrlThe reading list service URL. Copy the Public URL of the Reading List Service component from the endpoint table in the overview page for the relevant environment
    -
    6. -
  6. -

    Click Create.

    -
    7. -
-

Now you can proceed to deploy the web application.

-

Step 4: Deploy the web application

-

To deploy the web application component, follow the steps below:

-
    -
  1. In the left menu, click Deploy.
    2. -
  2. In the Build Area card, click Deploy Manually. The deployment may take a few minutes to complete.
    3. -
  3. Once the web application is deployed, copy the Web App URL from the development environment card.
    4. -
  4. Navigate to the web app URL. You can verify that the web app is successfully hosted.
    5. -
-

That's it! You can use a user created in your IdP and invoke the service through your web application.

- - - - - - -
-
- - -
- - - -
- - -
- - - -
-
-
- - - - - - - - - - - - - - - - - \ No newline at end of file diff --git a/en/site/consuming-services/create-a-subscription/index.html b/en/site/consuming-services/create-a-subscription/index.html deleted file mode 100644 index ddcb0e9d0..000000000 --- a/en/site/consuming-services/create-a-subscription/index.html +++ /dev/null @@ -1,3053 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - Create a subscription - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
-
- - - -
- - - - - - -
- - -
- -
- - - - - - - -
-
- - - -
-
-
- - - - -
-
-
- - - -
-
-
- - - -
-
-
- - - -
-
- - - - - - - - - - - - - - - - - - - - -

Create a subscription

- -

You must subscribe to a published API to use it in your application. New API subscriptions cover all minor versions within the subscribed API’s major version.

-

The subscription process is designed to ensure the secure authentication of API requests via application keys. Alternatively, you can generate credentials for an API without an explicit subscription to an application. However, this approach limits the capability to control advanced configurations such as access token expiry time, revoke token expiry time, ID token expiry time, and enabling access to the API without a secret. Generating keys in the API is recommended for testing or short-term usage but not for long-term production usage.

-

To subscribe to an API via an application, follow the steps given below:

-
    -
  1. Sign in to the Choreo Developer Portal.
    2. -
  2. In the Developer Portal header, click Applications.
    3. -
  3. On the My Applications page, click on the application with which you want to subscribe to an API.
    4. -
  4. In the left navigation menu, click Subscriptions.
    5. -
  5. In the Subscription Management pane that opens, click + Add APIs.
    6. -
  6. -

    Click Add to subscribe to an API. Depending on your requirement, you can subscribe to one or more APIs.

    -
    -

    Tip

    -

    When a new minor version of an API is published, the major version-based invocation URL will automatically route to the latest minor version within the subscribed API's major version. This ensures that existing client applications can continue to function without disruption while benefiting from the improvements or additions in the newer minor version.

    -
    -

    Add APIs

    -

    Once you subscribe to an API, you can invoke the API using the application keys.

    -
    7. -
- - - - - - -
-
- - -
- - - -
- - -
- -
-
-
-
- Copyright © WSO2 LLC (2023-2024) -
-
- Content licensed under CC By 4.0. | Sample code - licensed under Apache 2.0. -
-
-
-
-
- - - -
-
-
- - - - - - - - - - - - - - - - - \ No newline at end of file diff --git a/en/site/consuming-services/create-an-application/index.html b/en/site/consuming-services/create-an-application/index.html deleted file mode 100644 index 044f5b4af..000000000 --- a/en/site/consuming-services/create-an-application/index.html +++ /dev/null @@ -1,3108 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - Create an application - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- - - -
- - - - - - -
- - -
- -
- - - - - - - -
-
- - - -
-
-
- - - - -
-
-
- - - -
-
-
- - - -
-
-
- - - -
-
- - - - - - - - - - - - - - - - - - - - -

Create an application

- -

An application in Choreo is a logical representation of a physical application such as a mobile app, web app, device, etc. To consume an API in Choreo, you need to create an application that maps to your physical application and then subscribes to the required API over a usage policy plan that gives you a usage quota. A single application can have multiple subscriptions to APIs. Using the consumer key and consumer secret, you can generate an access token that you can use to invoke all the APIs subscribed to the same application.

-

This section walks you through the steps to create an application in Choreo.

-

Let's get started!

-

Step 1: Create an application

-

To create an application in the Choreo Developer Portal, follow the steps given below:

-
    -
  1. Sign in to the Choreo Developer Portal.
    2. -
  2. Click Applications. and then click +Create.
    3. -
  3. Enter a name and description for the application.
    4. -
  4. Click Create.
    5. -
-

This creates the application and opens the application overview page. You can view details such as the token type, workflow status, and the application owner of the API.

-

Step 2: Generate keys

-

Choreo provides an OAuth 2.0 bearer token-based authentication for API access. An API access token/key is a string that is passed as an HTTP header of an API request to authenticate access to the API.

-

Once you create an application in Choreo, you can generate credentials for it. When you generate credentials for the first time, Choreo provides a consumer key and consumer secret for the application. The consumer key becomes the unique identifier of the application and is used to authenticate the application.

-

The following section walks you through the steps to generate an API access token in Choreo.

-

Generate environment-specific keys and tokens

-

You can generate keys and tokens to invoke production and non-production endpoints separately.

-
-

Note

-

The capability to access production endpoints depends on your role. If you have permission to access production endpoints, you can generate keys and tokens to invoke production endpoints.

-
-
    -
  1. In the Choreo Developer Portal header, click Applications.
    2. -
  2. On the My Applications page, click on the application for which you want to generate keys and tokens.
    3. -
  3. In the left navigation menu, click the required environment under Credentials. This opens the Application Keys pane of the specific environment.
    4. -
  4. -

    Click to expand Advanced Configurations and review the options.

    -
      -
    • Grant Types: Select the grant types to use when generating the access token.
      • -
    • Public Client: Select Allow authentication without the client secret if your application can be considered as a public client such as an application running on a browser or mobile device.
      • -
    • PKCE for enhanced security: Select Mandatory if you want the application to send a code challenge in the authorization request and the corresponding code verifier in the token request. Asgardeo supports SHA-256 and plain.
      • -
    • Application access token expiry time: Specify the access token expiry time in seconds.
      • -
    • Refresh token expiry time: Specify the refresh token expiry time in seconds.
      • -
    • ID token expiry time: Specify the ID token expiry time in seconds.
      • -
    -
    5. -
  5. -

    Click Generate Credentials. This opens the Application Keys pane with values populated for the credentials.

    -
    6. -
-

You can use this consumer key and consumer secret values to generate an API access token by invoking the token endpoint. You can also revoke the access token by invoking the revoke endpoint.

-

To generate a test token for testing purposes, you can click Generate Token and copy the test token that is displayed. Alternatively, click cURL and copy the generated cURL command to use via a cURL client and obtain a test token.

-
-

Warning

Make sure you do not use the test token in your production environment.

-

-
- - - - - - -
-
- - -
- - - -
- - -
- -
-
-
-
- Copyright © WSO2 LLC (2023-2024) -
-
- Content licensed under CC By 4.0. | Sample code - licensed under Apache 2.0. -
-
-
-
-
- - - -
-
-
- - - - - - - - - - - - - - - - - \ No newline at end of file diff --git a/en/site/consuming-services/generate-an-access-token/index.html b/en/site/consuming-services/generate-an-access-token/index.html deleted file mode 100644 index d803fa0f8..000000000 --- a/en/site/consuming-services/generate-an-access-token/index.html +++ /dev/null @@ -1,3202 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - Generate an Access Token - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- - - -
- - - - - - -
- - -
- -
- - - - - - - -
-
- - - -
-
-
- - - - -
-
-
- - - -
-
-
- - - -
-
-
- - - -
-
- - - - - - - - - - - - - - - - - - - - -

Generate an Access Token

-

Using access tokens for request authorization strengthens security measures, particularly in preventing certain types of denial-of-service (DoS) attacks aimed at published APIs. API consumers generate access tokens to access the API, incorporating them into their HTTP header requests as simple string values.

-

When you register an application on the Developer Portal, you can generate a consumer key and a consumer secret for it. The consumer key and the consumer secret represent the credentials of the application. Similar to a user's username, the consumer key becomes the unique identifier of the application so that you can use it to authenticate the request to the API. Choreo issues an access token for the application against the mentioned consumer key.

-

This section walks you through the steps to generate an access token for your application in Choreo.

-

Let's get started!

-

Prerequisites

-

Before you try out this guide, be sure you have the following:

-
    -
  1. An application in the Choreo Developer Portal. If you do not have an application created, create a new application
    2. -
  2. Generate keys for the application.
    3. -
  3. Subscribe APIs to the application.
    4. -
-

Generate an access token via cURL

-

You can follow the steps below to generate an access token for your application via cURL:

-
    -
  1. In the Choreo Developer Portal header, click Applications.
    2. -
  2. On the My Applications page, click on the application for which you want to generate the token.
    3. -
  3. In the left navigation menu, click the required environment under Credentials. This opens the Application Keys pane of the specific environment.
    4. -
  4. Copy the Consumer Key, Consumer Secret, and Token Endpoint values.
    5. -
  5. -

    Use the following template and compile the cURL command with the values you copied in the above step.

    -
    -
    -
    -
    -
    -

    curl -k -X POST <token_endpoint> -d "grant_type=client_credentials" -H "Authorization: Basic <base64encode(consumer-key:consumer-secret)>"
-
    -6. Execute the cURL command to generate an access token.

    -
    6. -
-

Generate an access token via the Choreo Console (for testing purposes)

-

You can follow the steps below to generate an access token for testing purposes:

-
    -
  1. In the Choreo Developer Portal header, click Applications.
    2. -
  2. On the My Applications page, click on the application for which you want to generate keys and tokens.
    3. -
  3. In the left navigation menu, click the required environment under Credentials. This opens the Application Keys pane of the specific environment.
    4. -
  4. Click Generate Token.
    5. -
- - - - - - -
-
- - -
- - - -
- - -
- - - -
-
-
- - - - - - - - - - - - - - - - - \ No newline at end of file diff --git a/en/site/consuming-services/manage-application/index.html b/en/site/consuming-services/manage-application/index.html deleted file mode 100644 index 5fb6086aa..000000000 --- a/en/site/consuming-services/manage-application/index.html +++ /dev/null @@ -1,3335 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - Manage Application - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- - - -
- - - - - - -
- - -
- -
- - - - - - - -
-
- - - -
-
-
- - - - -
-
-
- - - -
-
-
- - - -
-
-
- - - -
-
- - - - - - - - - - - - - - - - - - - - -

Manage Applications

-

An application in Choreo is a logical representation of a physical application such as a mobile app, web app, device, etc. To consume an API in Choreo, you need to create an application that maps to your physical application and then subscribes to the required API over a usage policy plan that gives you a usage quota. A single application can have multiple subscriptions to APIs. Using the consumer key and consumer secret, you can generate an access token that you can use to invoke all the APIs subscribed to the same application.

-

This section walks you through the steps to create an application in Choreo.

-

Let's get started!

-

Step 1: Create an application

-

To create an application in the Choreo Developer Portal, follow the steps given below:

-
    -
  1. Sign in to the Choreo Developer Portal.
    2. -
  2. Click Applications. and then click +Create.
    3. -
  3. Enter a name and description for the application.
    4. -
  4. Click Create.
    5. -
-

This creates the application and opens the application overview page. You can view details such as the token type, workflow status, and the application owner of the API.

-

Step 2: Generate keys

-

Choreo provides an OAuth 2.0 bearer token-based authentication for API access. An API access token/key is a string that is passed as an HTTP header of an API request to authenticate access to the API.

-

Once you create an application in Choreo, you can generate credentials for it. When you generate credentials for the first time, Choreo provides a consumer key and consumer secret for the application. The consumer key becomes the unique identifier of the application and is used to authenticate the application.

-

The following section walks you through the steps to generate an API access token in Choreo.

-

Generate environment-specific keys and tokens

-

You can generate keys and tokens to invoke production and non-production endpoints separately.

-
-

Note

-

The capability to access production endpoints depends on your role. If you have permission to access production endpoints, you can generate keys and tokens to invoke production endpoints.

-
-
    -
  1. In the Choreo Developer Portal header, click Applications.
    2. -
  2. On the My Applications page, click on the application for which you want to generate keys and tokens.
    3. -
  3. In the left navigation menu, click the required environment under Credentials. This opens the Application Keys pane of the specific environment.
    4. -
  4. -

    Click to expand Advanced Configurations and review the options.

    -
      -
    • Grant Types: Select the grant types to use when generating the access token.
      • -
    • Public Client: Select Allow authentication without the client secret if your application can be considered as a public client such as an application running on a browser or mobile device.
      • -
    • PKCE for enhanced security: Select Mandatory if you want the application to send a code challenge in the authorization request and the corresponding code verifier in the token request. Asgardeo supports SHA-256 and plain.
      • -
    • Application access token expiry time: Specify the access token expiry time in seconds.
      • -
    • Refresh token expiry time: Specify the refresh token expiry time in seconds.
      • -
    • ID token expiry time: Specify the ID token expiry time in seconds.
      • -
    -
    5. -
  5. -

    Click Generate Credentials. This opens the Application Keys pane with values populated for the credentials.

    -
    6. -
-

You can use this consumer key and consumer secret values to generate an API access token by invoking the token endpoint. You can also revoke the access token by invoking the revoke endpoint.

-

To generate a test token for testing purposes, you can click Generate Token and copy the test token that is displayed. Alternatively, click cURL and copy the generated cURL command to use via a cURL client and obtain a test token.

-
-

Warning

Make sure you do not use the test token in your production environment.

-

-
-

Grant types

-

Choreo authentication is based on OAuth 2.0. In OAuth 2.0, grant types are methods that allow client applications to obtain an access token depending on the type of the resource owner, the type of the application, and the trust relationship between the authorization server and the resource owner.

-

Authorization code grant

-

The Authorization code flow provides a secure way for a client application to obtain an access token without exposing the user's credentials to the client application. The user only authenticates with the authorization server, which then issues an authorization code that can be exchanged for an access token.

-

This helps to protect user credentials and prevents credentials from being compromised by malicious client applications.

-

Refresh token grant

-

A refresh token is a token that you can use to get a new access token when your current access token is expired or when you need a new access token. You can use the refresh token grant type for this purpose. Issuing a refresh token is optional for the authorization server. If the authorization server issues a refresh token, it includes it in the response with the access token. You can use this refresh token and send it to the authorization server to obtain a new access token. Choreo's default authorization server, Asgardeo, issues refresh tokens for all grant types other than the client credentials grant type, as recommended by the OAuth 2.0 specification.

-
-

Note

-
    -
  • Keep your refresh token private, similar to the access token.
    • -
  • The process to get a new access token using the Refresh Token grant type requires no user interaction.
    • -
-
-

Client credentials grant

-

The client credentials flow provides a secure way for client applications to obtain an access token without user authentication. This is useful in scenarios where the client application needs to access its own resources, such as data storage or APIs, but does not require access to user data. However, it is important to ensure that the client credentials are kept secure because any party who has these credentials can obtain access tokens and access the client's resources.

-

Implicit grant

-

The implicit grant flow is an OAuth 2.0 grant type that enables a client application to obtain an access token directly from the authorization server without an intermediate authorization code exchange. This flow is commonly used in browser-based applications where the client application runs in a web browser.

-

However, it is important to note that the access token is exposed in the browser's URL fragment, which can make it vulnerable to certain types of attacks, such as cross-site scripting (XSS). As a result, this flow is typically not recommended for applications that require high security.

-

Password grant

-

The password grant flow is an OAuth 2.0 grant type that enables a client application to obtain an access token by presenting the user's username and password directly to the authorization server. This flow is generally considered less secure than other grant types, as it requires the client application to handle and transmit the user's credentials.

-

The password grant is primarily used in scenarios where the client application is highly trusted, and the user experience is prioritized over security concerns. It is generally not recommended for use in public-facing applications or scenarios where sensitive data is accessed.

-

Revoke access tokens

-

Revoking JWT access tokens can be challenging due to their self-validating nature. Once a token is issued, it contains all the necessary information within itself to validate its authenticity, without requiring additional server-side lookups or interactions.

-

It is recommended to use an expiry time that is not more than 900 seconds.

-

In traditional session-based authentication, the server can easily revoke a session by invalidating its associated session ID. However, in the case of JWTs, there is no central authority that maintains a list of valid or invalid tokens. As a result, revoking a JWT token requires the use of denylist or allowlist techniques, which can add additional complexity to the authentication flow and may not always be foolproof.

-

To mitigate these challenges, it is recommended to use short-lived JWT access tokens and regularly refresh them. This reduces the risk of unauthorized access if a token is stolen or leaked, as the token will expire after a short period of time. Additionally, implementing other security measures such as strong encryption and secure token storage can further enhance the security of JWT-based authentication.

-

The Choreo Developer Portal keeps the lifespan of a token to 15 minutes (900 seconds) by default. Application Developers can increase the time if necessary, but as mentioned above, it is recommended to keep it to the minimal possible value.

- - - - - - -
-
- - -
- - - -
- - -
- - - -
-
-
- - - - - - - - - - - - - - - - - \ No newline at end of file diff --git a/en/site/consuming-services/manage-subscription/index.html b/en/site/consuming-services/manage-subscription/index.html deleted file mode 100644 index ced6385a4..000000000 --- a/en/site/consuming-services/manage-subscription/index.html +++ /dev/null @@ -1,3109 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - Manage Subscription - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- - - -
- - - - - - -
- - -
- -
- - - - - - - -
-
- - - -
-
-
- - - - -
-
-
- - - -
-
-
- - - -
-
-
- - - -
-
- - - - - - - - - - - - - - - - - - - - -

Manage Subscriptions

-

You must subscribe to a published API to use it in your application. New API subscriptions cover all minor versions within the subscribed API’s major version.

-

The subscription process is designed to ensure the secure authentication of API requests via application keys. Alternatively, you can generate credentials for an API without an explicit subscription to an application. However, this approach limits the capability to control advanced configurations such as access token expiry time, revoke token expiry time, ID token expiry time, and enabling access to the API without a secret. Generating keys in the API is recommended for testing or short-term usage but not for long-term production usage.

-

To subscribe to an API via an application, follow the steps given below:

-
    -
  1. Sign in to the Choreo Developer Portal.
    2. -
  2. In the Developer Portal header, click Applications.
    3. -
  3. On the My Applications page, click on the application with which you want to subscribe to an API.
    4. -
  4. In the left navigation menu, click Subscriptions.
    5. -
  5. In the Subscription Management pane that opens, click + Add APIs.
    6. -
  6. -

    Click Add to subscribe to an API. Depending on your requirement, you can subscribe to one or more APIs.

    -
    -

    Tip

    -

    When a new minor version of an API is published, the major version-based invocation URL will automatically route to the latest minor version within the subscribed API's major version. This ensures that existing client applications can continue to function without disruption while benefiting from the improvements or additions in the newer minor version.

    -
    -

    Add APIs

    -

    Once you subscribe to an API, you can invoke the API using the application keys.

    -
    7. -
- - - - - - -
-
- - -
- - - -
- - -
- - - -
-
-
- - - - - - - - - - - - - - - - - \ No newline at end of file diff --git a/en/site/consuming-services/share-applications/index.html b/en/site/consuming-services/share-applications/index.html deleted file mode 100644 index 3ed1a49a4..000000000 --- a/en/site/consuming-services/share-applications/index.html +++ /dev/null @@ -1,3108 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - Share Applications - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- - - -
- - - - - - -
- - -
- -
- - - - - - - -
-
- - - -
-
-
- - - - -
-
-
- - - -
-
-
- - - -
-
-
- - - -
-
- - - - - - - - - - - - - - - - - - - - -

Share Applications

-

Choreo's application-sharing feature allows you to share your applications with members within your organization. This facilitates collaborative efforts when there is a need for multiple members to work on the same application.

-

Follow the steps given below to share an application with members of your organization:

-
    -
  1. Sign in to the Choreo Developer Portal and click the Applications tab.
    2. -
  2. On the Applications page, click on the application you want to share.
    3. -
  3. On the Application Overview page that opens, click the Share button displayed on the right side.
    4. -
  4. -

    In the Share Application dialog, enter one or more email addresses depending on the members with whom you want to share the applications.

    -
    -

    Note

    -

    You must type an email address and press enter for it to get added.

    -
    -
    5. -
  5. -

    Click Confirm. This will share the application in read-only mode with the specified members.

    -
    6. -
-

To see the members with whom the application is shared, go to the Application Overview page and take a look at the email addresses in the Shared with field.

- - - - - - -
-
- - -
- - - -
- - -
- - - -
-
-
- - - - - - - - - - - - - - - - - \ No newline at end of file diff --git a/en/site/deploy/deploy-a-ballerina-application/index.html b/en/site/deploy/deploy-a-ballerina-application/index.html deleted file mode 100644 index 01f424356..000000000 --- a/en/site/deploy/deploy-a-ballerina-application/index.html +++ /dev/null @@ -1,15 +0,0 @@ - - - - - - Redirecting... - - - - - - -Redirecting... - - diff --git a/en/site/deploy/deploy-a-containerized-application/index.html b/en/site/deploy/deploy-a-containerized-application/index.html deleted file mode 100644 index 71782578a..000000000 --- a/en/site/deploy/deploy-a-containerized-application/index.html +++ /dev/null @@ -1,15 +0,0 @@ - - - - - - Redirecting... - - - - - - -Redirecting... - - diff --git a/en/site/deploy/devops/configs-and-secrets/index.html b/en/site/deploy/devops/configs-and-secrets/index.html deleted file mode 100644 index 7d2e23452..000000000 --- a/en/site/deploy/devops/configs-and-secrets/index.html +++ /dev/null @@ -1,15 +0,0 @@ - - - - - - Redirecting... - - - - - - -Redirecting... - - diff --git a/en/site/deploy/devops/containers/index.html b/en/site/deploy/devops/containers/index.html deleted file mode 100644 index 285bc5f10..000000000 --- a/en/site/deploy/devops/containers/index.html +++ /dev/null @@ -1,15 +0,0 @@ - - - - - - Redirecting... - - - - - - -Redirecting... - - diff --git a/en/site/deploy/devops/health-checks/index.html b/en/site/deploy/devops/health-checks/index.html deleted file mode 100644 index 5bf5a2814..000000000 --- a/en/site/deploy/devops/health-checks/index.html +++ /dev/null @@ -1,15 +0,0 @@ - - - - - - Redirecting... - - - - - - -Redirecting... - - diff --git a/en/site/deploy/devops/runtime/index.html b/en/site/deploy/devops/runtime/index.html deleted file mode 100644 index a97ad5a0a..000000000 --- a/en/site/deploy/devops/runtime/index.html +++ /dev/null @@ -1,15 +0,0 @@ - - - - - - Redirecting... - - - - - - -Redirecting... - - diff --git a/en/site/deploy/devops/scaling/index.html b/en/site/deploy/devops/scaling/index.html deleted file mode 100644 index 1be5bf027..000000000 --- a/en/site/deploy/devops/scaling/index.html +++ /dev/null @@ -1,15 +0,0 @@ - - - - - - Redirecting... - - - - - - -Redirecting... - - diff --git a/en/site/deploy/devops/storage/index.html b/en/site/deploy/devops/storage/index.html deleted file mode 100644 index abb2b9867..000000000 --- a/en/site/deploy/devops/storage/index.html +++ /dev/null @@ -1,15 +0,0 @@ - - - - - - Redirecting... - - - - - - -Redirecting... - - diff --git a/en/site/develop-components/bring-your-own-image/index.html b/en/site/develop-components/bring-your-own-image/index.html deleted file mode 100644 index 99b46217c..000000000 --- a/en/site/develop-components/bring-your-own-image/index.html +++ /dev/null @@ -1,3481 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - Bring Your Own Image - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- - - -
- - - - - - -
- - -
- -
- - - - - - - -
-
- - - -
-
-
- - - - -
-
-
- - - -
-
-
- - - -
-
-
- - - -
-
- - - - - - - - - - - - - - - - - - - - -

Bring Your Own Image (BYOI)

-

Choreo allows you to deploy and manage prebuilt container images from external container registries as Choreo components. This enables you to deploy and effectively manage your container images within the Choreo environment.

-
-

Info

-

This feature is currently only available on private data planes (PDPs) for the following component types:

-
    -
  • Service
    • -
  • Web Application
    • -
  • Scheduled Task
    • -
  • Manual Task
    • -
-
-

Prerequisites

-

Before you try out this guide, ensure you have the following:

-
    -
  • -

    A container registry: Ensure you have a container registry containing the images you want to deploy. Choreo is compatible with various container registries, including but not limited to GCR (Google Container Registry), ACR (Azure Container Registry), GitHub Container Registry, and Docker Hub.

    -
    • -
  • -

    An image in the registry: You need an image ready for deployment.

    -
    • -
  • -

    (Optional) An external build/CI pipeline: This is to initiate automatic deployments during the build process outside of Choreo.

    -
    • -
-

When using a container registry to deploy a component, Choreo cannot create an image from the source code (Git) or initiate a new deployment when a new image is ready. However, you can use your existing build process to trigger a deployment on Choreo by sending an HTTP POST request to a webhook with the new image details.

-

This feature is currently only available on private data planes (PDPs). You can find this option under Deploy an image from a container registry in the Select Source step during component creation for service components, web applications, scheduled tasks, and manual tasks.

-

Step 1: Register a container registry

-

To get started, establish a connection between your container registry and Choreo.

-
-

Info

-

When you use your Choreo credentials, Choreo does not pull your images into its control plane. Instead, it functions as an orchestrator, facilitating your data plane's ability to retrieve images from an external container registry. Choreo passes on these credentials to the data plane for authentication and access.

-
-

To register your container registry, follow these steps:

-
    -
  1. Sign in to the Choreo Console.
    2. -
  2. In the Choreo Console header, go to the Organization list and select your organization.
    3. -
  3. In the left navigation menu, click Settings. This opens the organization settings page.
    4. -
  4. Click the Credentials tab and then click the Container Registries tab.
    5. -
  5. Click +Add Registry to configure the Git repository connection.
    6. -
  6. Specify a Registry Display Name.
    7. -
  7. Select the Authentication Type. Fill in the required information depending on your authentication type. For details on each authentication type, see Authentication types.
    8. -
  8. Click Save.
    9. -
-

Authentication types

-

Choreo provides the following authentication options:

-

Public (anonymous) access

-

You can use this option to establish a connection with a container registry that permits unrestricted public or anonymous access (for example, Public Docker Hub). In this case, only the registry host information is necessary.

-

For example, the following are the Docker Hub registry hosts for reference:

- - - - - - - - - - - - - - - - - -
VendorRegistry host
Docker Hub (public repositories)registry.hub.docker.com
Docker Hub (private repositories)registry.docker.com
-

* If necessary, you can use other mirrors instead of the above.

-

Basic authentication

-

To use basic authentication to authenticate to the container registry, you must provide the username and password.

-

Docker config

-

You can provide a Docker config in JSON format to authenticate to the container registry. This option only allows you to register one container registry. That is, it only allows a single registry under auths.

-

You must provide the credentials directly within the configuration. Choreo cannot utilize references to executable authentication plugins.

-

Sample Docker config format:

-
    {
-    "auths": {
-        "index.docker.io/v1/": {
-        "auth": "c3R...zE2"
-        }
-    }
-    }
-
- -

Vendor-specific authentication

-

This option is specifically for private data planes, where your cloud provider manages authentication at the Kubernetes level. Choreo requires knowledge of the registry host because the data plane already possesses implicit (preconfigured) access to the registry.

-

Follow the guidelines below based on your container registry:

-
-
-
-

Azure Container Registry

-

Recommended authentication options:

-
    -
  • -

    Service principal-based basic authentication

    -
    • -
  • -

    Vendor-specific authentication on Azure private data planes

    -

    Contact Choreo support to enable infrastructure-level private access to your registry from your Azure private data plane on AKS. If you are on a self-managed PDP on Azure, follow this guide.

    -
    • -
-
-
-

Google Artifact Registry

-

Recommended authentication options:

- -
-
-

Elastic Container Registry

-

ECR does not allow the creation of static access passwords for basic authentication. The passwords (that is, access tokens) provided by AWS are only valid for 10 hours and must be manually regenerated. However, when an ECR is attached to an EKS cluster at an infrastructure level, this limitation does not apply because the authentication is handled by AWS internally. For details, see https://docs.aws.amazon.com/AmazonECR/latest/userguide/registry_auth.html.

-

Choreo recommends using ECR when you are exclusively on an AWS private data plane using the vendor-specific authentication option. Contact Choreo support to enable a private connection between your ECR and the underlying EKS clusters on your data plane. If you are on a self-managed PDP, you can follow this guide.

-
-
-

Recommended authentication options:

-
    -
  • -

    Basic authentication

    -

    Use your Docker Hub username/password or an access token. You can generate an access token from your Docker Hub account settings and use it in place of the password. For details, see https://docs.docker.com/docker-hub/access-tokens/.

    -
    • -
  • -

    Docker config

    -

    Sign in to the Docker CLI and copy the contents of the docker config JSON. Note that external credential stores and multiple repositories within the same config object are not supported. For more information, see https://docs.docker.com/engine/reference/commandline/login/.

    -
    • -
-
-
-

GitHub Container Registry

-

Recommended authentication option:

-
    -
  • -

    Basic authentication using a PAT token

    -

    Create a personal access token (PAT) and use it in place of the password. You cannot use your own GitHub password. You must provide a PAT token.

    -
    • -
-
-
-
-

Step 2: Create a component in Choreo

-
    -
  1. In the left navigation, click Overview and select your project. Alternatively, select your project from the Project list in the Choreo Console header.
    2. -
  2. Under Component Listing click + Create.
    3. -
  3. Select your component type (BYOI is only available for Service, Web Application, Scheduled Task, or Manual Task components).
    4. -
  4. -

    Enter a display name, a unique name, and a description for the component.

    -
    -

    Info

    -

    In the Component Name field, you must specify a name to uniquely identify the component in various contexts. The value is editable only at the time you create the component. You cannot change the name after you create the component.

    -
    -
    5. -
  5. -

    Click either the Docker Hub tab or the Container Registry tab depending on your vendor.

    -
    6. -
  6. Under Deploy an image from Container Registry/Docker Hub, select the container registry you have registered in Step 1.
    7. -
  7. -

    Enter the full image URL. The image URL format in general is as follows: - [container-registry-host]/[repository-name]/[image-name]:[tag]

    -
    -

    Tip

    -

    When a public image from Docker Hub lacks a specified repository name, it typically defaults to /library/. For example, you can access the public Nginx image https://hub.docker.com/_/nginx as registry.hub.docker.com/library/nginx:1.25.

    -
    -
    8. -
-

Step 3: Deploy the component in Choreo

-

To deploy the component and bring your image to Choreo, follow the steps given below:

-
    -
  1. In the left navigation menu, click Deploy.
    2. -
  2. In the Build Area card, click Update Image & Deploy.
    3. -
  3. In the Endpoint pane that opens, you can see the endpoint ready to be deployed. Click the edit icon next to the endpoint name. Optionally, you can define the endpoints for your service when you manually deploy the service. For more information, see Expose service endpoints.
    4. -
  4. Change the Network Visibility to Public. This setting securely exposes the endpoint for consumption.
    5. -
  5. -

    Click Update.

    -
    -

    Info

    -

    In this example, you deploy a Ballerina service as a REST endpoint. Therefore, Choreo generated the REST endpoint automatically. If you deploy a non-Ballerina service, you must manually add the REST endpoint and set the network visibility to Public.

    -
    -
    6. -
  6. -

    Select your update image option. Refer to the update options listed below.

    -

    You have the capability of updating the image when you are deploying the component in Choreo in one of the following three ways:

    - - - - - - - - - - - - - - - - - - - - - -
    OptionDescription
    Update Image TagThis option allows you to update the tag of the image.
    Update Image URLWith this option, you can change the image name, tag, and the image repository of the image URL.
    Previous ImagesThis option allows you to select a previous image and redeploy the image.
    -
    7. -
  7. -

    Click Deploy. This deploys the service to the development environment.

    -
    8. -
-

Step 4: Expose service endpoints

-
-

Info

-

This section only applies to service components.

-
-

After creating a service component in Choreo, you have the option to define the endpoints for your service when manually deploying a new image.

-
    -
  1. In the left navigation menu, click Deploy.
    2. -
  2. In the Build Area card, click Update Image & Deploy.
    3. -
  3. In the Endpoint pane that opens, optionally, you can define the endpoints for your service when you manually deploy the service.
    4. -
  4. Click Create/Update Endpoints.
    5. -
  5. Under the Edit endpoints.yaml section, you can edit the endpoints YAML file in the provided editor. - Alternatively, you can upload the associated API specification/schema files (OpenAPI/GraphQL schemas). Instead of specifying the file path, you can also reference this file in the endpoints.yaml file by its file name, similar to the Git-based Choreo components. The endpoints template follows the standard definitions for defining endpoints in Choreo. For more details, see Configure Endpoints.
    6. -
-

Auto-deploy images in Choreo with an external CI/build pipeline

-

Choreo does not have automatic detection and deployment for newly added images or tags in the linked container registry. To overcome this limitation, Choreo allows you to integrate your own CI pipelines and initiate deployments manually. This approach enables you to use your existing CI setup or build a pipeline for image creation and pushing. You can then trigger automatic deployments using a webhook.

-

Follow the steps below to configure your CI/build pipeline:

-
    -
  1. Build and push the container image associated with a Choreo component to your container registry.
    2. -
  2. In the left navigation menu, click DevOps and then click External CI.
    3. -
  3. -

    Generate a token for your CI pipeline from the Manage Tokens section.

    -
    -

    Note

    -
      -
    • The tokens are bound to a specific component.
      • -
    • It is recommended to reference the token from a secure location available to your CI pipeline. For example, use a GitHub secret if you are using GitHub Actions.
      • -
    -
    -
    4. -
  4. -

    To trigger an automatic deployment to your development environment, you can initiate an HTTP POST request to the Choreo webhook endpoint with the updated image details. Alternatively, you can use the provided Webhook snippets. This action will seamlessly deploy the image to the development environment.

    -
    5. -
- - - - - - -
-
- - -
- - - -
- - -
- - - -
-
-
- - - - - - - - - - - - - - - - - \ No newline at end of file diff --git a/en/site/develop-components/configure-endpoints-body/index.html b/en/site/develop-components/configure-endpoints-body/index.html deleted file mode 100644 index 64a79c872..000000000 --- a/en/site/develop-components/configure-endpoints-body/index.html +++ /dev/null @@ -1,3457 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - Configure endpoints body - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- - - -
- - - - - - -
- - -
- -
- - - - - - - -
-
- - - -
-
-
- - - - -
-
-
- - - -
-
-
- - - -
-
-
- - - -
-
- - - - - - - - - - - - - - - - - - - - -

Configure endpoints body

- -

Services and integrations are exposed to other services, integrations, or applications through endpoints. A service or an integration can expose multiple endpoints, each representing a unique entry point into the service. For example, a service may expose a REST API endpoint and a GraphQL endpoint, each providing different ways to interact with the service. Endpoints provide specific details for how the service or the integration can be consumed. For instance, the port number, protocol, and the schema such as open API specification (OAS) or GraphQL schema. By defining these details, endpoints make it possible for other services, integrations, and applications to discover and interact with the service in a standardized way.

-

Choreo defines endpoints by combining port binding, protocol, endpoint name, network visibility, endpoint schema, and additional protocol-related fields. The following table describes each attribute of an endpoint.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldDescription
NameA unique identifier for the endpoint within the service component.
PortThe network port on which the endpoint is accessible.
TypeThe endpoint protocol. Supported protocols: REST, GraphQL, gRPC, UDP, and TCP.
Network VisibilityDetermines the level of visibility of an endpoint. Possible values are:
  • Project: Allows components within the same project to access the endpoint.
  • Organization: Allows any component within the same organization to access the endpoint but restricts access to components outside the organization.
  • Public: Allows any client to access the endpoint, regardless of location or organization.
SchemaSpecifies the structure and format of the data exchanged through the endpoint.
Context (HTTP and GraphQL only)A context path that you add to the endpoint's URL for routing purposes.
-

Configure endpoints

-

The method of defining endpoints depends on the buildpack. For buildpacks other than Ballerina and WSO2 MI, it is required to have an endpoints.yaml file in project root directory to create the Service component.

-

Configure endpoints with buildpacks (except Ballerina)

-

When you build a service component using any other buildpacks(Java, Python, NodeJS, Ruby, PHP, Go, Dockerfile, etc) other than Ballerina and WSO2 MI, you can configure the endpoint details with the endpoints.yaml configuration file. You must place this file inside the .choreo directory at the build context path and commit it to the source repository.

-

See Understanding the endpoints.yaml file to learn about the endpoints.yaml file.

-

Configure endpoints with the Ballerina buildpack

-

When you create a service component with the Ballerina buildpack, Choreo automatically detects the endpoint details for REST APIs. You can override the auto-generated endpoint configuration by providing the endpoints.yaml file in the source directory.

-
-

Note

-

Automatic endpoint generation is not supported for dynamic endpoint parameters such as variable ports. Therefore, you must use an endpoint.yaml file to define dynamic endpoint parameters.

-
-

See Understanding the endpoints.yaml file to learn about the endpoints.yaml file.

-

Learn the endpoints.yaml file

-

The endpoints.yaml file has a specific structure and contains the following details:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldRequiredDescription
versionRequiredThe version of the endpoints.yaml file.
nameRequiredA unique name for the endpoint, which Choreo will use to generate the managed API.
portRequiredThe numeric port value that gets exposed via this endpoint.
typeRequiredThe type of traffic this endpoint is accepting, such as REST, GraphQL, gRPC, UDPor TCP. Currently, the MI preset supports only the REST type.
networkVisibilityRequiredThe network level visibility of this endpoint, which defaults to Public if not specified. Accepted values are Project, Organization, or Public.
contextRequiredThe context (base path) of the API that Choreo exposes via this endpoint.
schemaFilePathRequiredThe 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.
-

Sample endpoints.yaml

-

File location:

-
<docker-build-context-path>/.choreo/endpoints.yaml
-
- -
-

Note

-
    -
  • -

    For components built with Ballerina buildpack docker-build-context-path should be replaced with component-root. -For example: <component-root>/.choreo/endpoints.yaml

    -
    • -
  • -

    For components built with WSO2 MI buildpack docker-build-context-path should be replaced with <Project Path>. -For example: <Project Path>/.choreo/endpoints.yaml

    -
    • -
-
-

File content:

-
# +required Version of the endpoint configuration YAML
-version: 0.1
-
-# +required List of endpoints to create
-endpoints:
-  # +required Unique name for the endpoint. (This name will be used when generating the managed API)
-- name: Greeting Service
-  # +required Numeric port value that gets exposed via this endpoint
-  port: 9090
-  # +required Type of the traffic this endpoint is accepting. Example: REST, GraphQL, etc.
-  # Allowed values: REST, GraphQL, GRPC, UDP, TCP
-  type: REST
-  # +optional Network level visibility of this endpoint. Defaults to Public
-  # Accepted values: Project|Organization|Public.
-  networkVisibility: Project
-  # +optional Context (base path) of the API that is exposed via this endpoint.
-  # This is mandatory if the endpoint type is set to REST or GraphQL.
-  context: /greeting
-  # +optional Path to the schema definition file. Defaults to wild card route if not provided
-  # This is only applicable to REST endpoint types.
-  # The path should be relative to the docker context.
-  schemaFilePath: greeting_openapi.yaml
-
- -

Apply advanced component connection configurations

-

The component-config.yaml file extends the capabilities of endpoints.yaml by introducing enhancements that allow you to apply advanced inbound and outbound connection configurations.

-
-

Beta release

-
    -
  • The current version of the component-config.yaml file is considered stable. However, it is important to note that the configuration schema may undergo changes and improvements based on user feedback.
    • -
  • Support for the current schema will remain even when new versions are introduced.
    • -
-
-

The component-config.yaml file complements and enhances the existing endpoint configuration process. It allows you to define how your service's endpoints (inbound connections) are exposed and how your service connects to external services or components (outbound connections).

-
    -
  • -

    Inbound configurations: This configuration section is for you to define inbound connections, Similar to endpoints.yaml, you can define how your service endpoints are exposed. It aligns seamlessly with the existing endpoint schema structure.

    -
    • -
  • -

    Outbound configurations: This configuration section is for you to specify outbound connection details, including service connections. The Choreo Internal Marketplace facilitates creating connections with existing services. To learn more about Choreo Marketplace, see Choreo Marketplace.

    -
    • -
-
-

Note

-
    -
  • If both component-config.yaml and endpoints.yaml are defined in the .choreo path, the component-config.yaml file takes priority.
    • -
  • Outbound connections are not supported for deprecated components and WSO2 MI buildpack components.
    • -
-
-

Learn the component-config.yaml file

-

The component-config.yaml file has a specific structure and contains the following details:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldRequiredDescription
apiVersionRequiredThe version of the component-config.yaml file defaults to core.choreo.dev/v1beta1.
kindRequiredThe resource type of the file defaults to ComponentConfig.
spec.inboundOptionalThe list of inbound connection configurations.
spec.outboundOptionalThe list of outbound connection configurations.
-

Inbound connection configurations (spec.inbound)

-

In the spec.inbound configuration section, you can specify endpoints to set up inbound connections. To specify endpoints, you can follow the existing endpoints schema structure. For details on the endpoints schema structure, see the endpoints schema documentation.

-

Outbound connection configurations (spec.outbound)

-

In the spec.outbound section, you can define serviceReferences. To define serviceReferences, you can use the service references generated in the Internal Marketplace when creating a service connection. To copy the outbound connection configurations, see the inline developer guide that is available when you create a connection.

-

The serviceReferences schema has a specific structure and contains the following details:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldRequiredDescription
nameRequiredA unique name for the service reference.
connectionConfigRequiredA unique name for the connection instance.
envOptionalThe list of environment variable mappings that get injected into the container.
env.fromRequiredThe key name of the connection configuration.
env.toRequiredThe environment variable that gets injected into the container.
-
-

Note

-

Choreo automatically generates outbound connection configurations upon the creation of a connection within the internal marketplace. The properties such as name, connectionConfig, and env.from are automatically generated. However, you must manually set the env.to value.

-
-

Sample component-config.yaml

-

File location:

-
<docker-build-context-path>/.choreo/component-config.yaml
-
- -
-

Note

-
    -
  • For components built using the Ballerina buildpack, you must replace docker-build-context-path with the component-root. -For example, <component-root>/.choreo/component-config.yaml.
    • -
  • For components built using the WSO2 MI buildpack, you must replace docker-build-context-path with the <Project Path>. -For example, <Project Path>/.choreo/component-config.yaml.
    • -
-
-

File content:

-
apiVersion: core.choreo.dev/v1beta1
-kind: ComponentConfig
-spec:
-  # +optional Incoming connection details for the component (AKA endpoints).
-  inbound:
-    # +required Unique name for the endpoint. (This name will be used when generating the managed API)
-    - name: Greeting Service
-      # +required Numeric port value that gets exposed via the endpoint
-      port: 9090
-      # +required Type of traffic that the endpoint is accepting. For example: REST, GraphQL, etc.
-      # Allowed values: REST, GraphQL, GRPC, TCP, UDP.
-      type: REST
-      # +optional Network level visibility of the endpoint. Defaults to Public
-      # Accepted values: Project|Organization|Public.
-      networkVisibility: Public
-      # +optional Context (base path) of the API that gets exposed via the endpoint.
-      # This is mandatory if the endpoint type is set to REST or GraphQL.
-      context: /greeting
-      # +optional The path to the schema definition file. Defaults to wildcard route if not specified.
-      # This is only applicable to REST endpoint types.
-      # The path should be relative to the Docker context.
-      schemaFilePath: greeting_openapi.yaml
-  # +optional Outgoing connection details for the component.
-  outbound:
-    # +optional Defines the service references from the Internal Marketplace.
-    serviceReferences:
-      # +required Name of the service reference.
-      - name: choreo:///apifirst/mttm/mmvhxd/ad088/v1.0/PUBLIC
-        # +required Name of the connection instance.
-        connectionConfig: 19d2648b-d29c-4452-afdd-1b9311e81412
-        # +optional Environment variables injected to the component for connection configuration.
-        env:
-          # +required Key name of the connection configuration.
-          - from: ServiceURL
-            # +required Environment variable injected to the container.
-            to: SERVICE_URL
-
- -

Expose endpoints as managed APIs

-

Exposing endpoints as managed APIs is crucial to ensure secure and controlled access to the services being exposed. When a user wants to expose their written service to the outside world or to the organization at large, there is an inherent security risk involved. To mitigate this risk, the Choreo platform is built with an internal (access within the organization only) or external (publicly accessible) gateway that is protected with Choreo API management making the services secure by design.

-
-

Note

-

This feature is not available for gRPC, UDP, and TCP endpoints.

-
-

If you want to expose an endpoint as a managed API in Choreo, you need to set the network visibility to either Organization or Public. This allows the endpoint to be exposed through the Choreo API Gateway, which provides a number of benefits, including:

-
    -
  • Expose APIs to external and internal consumers
    • -
  • Full lifecycle API Management
    • -
  • API throttling
    • -
  • Secure APIs with industry-standard authorization flows
    • -
  • API analytics and monitoring
    • -
-

Once you deploy the service component, Choreo will expose the endpoint as a managed API through the Choreo API Gateway. You can then use the full lifecycle API management features provided by Choreo to test, deploy, maintain, monitor, and manage your API using the API management features.

-

Understand the default component URL

-

The default URL of a component corresponds to the default endpoint of the component and is structured as follows:

-

<domain>/<project-name>/<component-name>

-

This URL does not include the default endpoint name. For all other endpoints, the URL structure includes the endpoint name, as follows:

-

<domain>/<project-name>/<component-name>/<endpoint-name>

-

If a component has multiple endpoints, Choreo allows you to change the endpoint corresponding to the default component URL. For a component with a single endpoint, the default URL automatically corresponds to that endpoint.

-

Change the default endpoint of a component

-

To change the default endpoint of a component, follow the steps given below:

-
-

Note

-
    -
  • You cannot change the default endpoint if it has associated published APIs. You must go to the Lifecycle page and unpublish the relevant APIs before updating the default endpoint. For instructions on unpublishing an API, see Lifecycle Management.
    • -
  • Choreo does not allow you to change the default endpoint of a component if you create multiple deployment tracks within its current major version, or promote the component beyond its initial environment.
    • -
-
-
    -
  1. Sign in to the Choreo Console.
    2. -
  2. In the Component Listing pane, click on the component for which you want to change the default endpoint.
    3. -
  3. In the left navigation menu, click Deploy.
    4. -
  4. On the Deploy page, go to the Set Up card and click Configure & Deploy.
    5. -
  5. In the Environment Configurations pane that opens, click Next.
    6. -
  6. In the File Mount pane that opens, click Next.
    7. -
  7. In the Endpoint Details pane that opens, click the Default Endpoint list, select the endpoint you want to set as the default endpoint, and then click Update.
    8. -
  8. Click Deploy. This deploys the component with the selected endpoint as the default, and the default URL will now correspond to this endpoint.
    9. -
- - - - - - -
-
- - -
- - - -
- - -
- -
-
-
-
- Copyright © WSO2 LLC (2023-2024) -
-
- Content licensed under CC By 4.0. | Sample code - licensed under Apache 2.0. -
-
-
-
-
- - - -
-
-
- - - - - - - - - - - - - - - - - \ No newline at end of file diff --git a/en/site/develop-components/configure-endpoints/index.html b/en/site/develop-components/configure-endpoints/index.html deleted file mode 100644 index f0d09824d..000000000 --- a/en/site/develop-components/configure-endpoints/index.html +++ /dev/null @@ -1,3607 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - Configure Endpoints - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- - - -
- - - - - - -
- - -
- -
- - - - - - - -
-
- - - -
-
-
- - - - -
-
-
- - - -
-
-
- - - -
-
-
- - - -
-
- - - - - - - - - - - - - - - - - - - - -

Configure Endpoints

-

Services and integrations are exposed to other services, integrations, or applications through endpoints. A service or an integration can expose multiple endpoints, each representing a unique entry point into the service. For example, a service may expose a REST API endpoint and a GraphQL endpoint, each providing different ways to interact with the service. Endpoints provide specific details for how the service or the integration can be consumed. For instance, the port number, protocol, and the schema such as open API specification (OAS) or GraphQL schema. By defining these details, endpoints make it possible for other services, integrations, and applications to discover and interact with the service in a standardized way.

-

Choreo defines endpoints by combining port binding, protocol, endpoint name, network visibility, endpoint schema, and additional protocol-related fields. The following table describes each attribute of an endpoint.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldDescription
NameA unique identifier for the endpoint within the service component.
PortThe network port on which the endpoint is accessible.
TypeThe endpoint protocol. Supported protocols: REST, GraphQL, gRPC, UDP, and TCP.
Network VisibilityDetermines the level of visibility of an endpoint. Possible values are:
  • Project: Allows components within the same project to access the endpoint.
  • Organization: Allows any component within the same organization to access the endpoint but restricts access to components outside the organization.
  • Public: Allows any client to access the endpoint, regardless of location or organization.
SchemaSpecifies the structure and format of the data exchanged through the endpoint.
Context (HTTP and GraphQL only)A context path that you add to the endpoint's URL for routing purposes.
-

Configure endpoints

-

The method of defining endpoints depends on the buildpack. For buildpacks other than Ballerina and WSO2 MI, it is required to have an endpoints.yaml file in project root directory to create the Service component.

-

Configure endpoints with buildpacks (except Ballerina)

-

When you build a service component using any other buildpacks(Java, Python, NodeJS, Ruby, PHP, Go, Dockerfile, etc) other than Ballerina and WSO2 MI, you can configure the endpoint details with the endpoints.yaml configuration file. You must place this file inside the .choreo directory at the build context path and commit it to the source repository.

-

See Understanding the endpoints.yaml file to learn about the endpoints.yaml file.

-

Configure endpoints with the Ballerina buildpack

-

When you create a service component with the Ballerina buildpack, Choreo automatically detects the endpoint details for REST APIs. You can override the auto-generated endpoint configuration by providing the endpoints.yaml file in the source directory.

-
-

Note

-

Automatic endpoint generation is not supported for dynamic endpoint parameters such as variable ports. Therefore, you must use an endpoint.yaml file to define dynamic endpoint parameters.

-
-

See Understanding the endpoints.yaml file to learn about the endpoints.yaml file.

-

Learn the endpoints.yaml file

-

The endpoints.yaml file has a specific structure and contains the following details:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldRequiredDescription
versionRequiredThe version of the endpoints.yaml file.
nameRequiredA unique name for the endpoint, which Choreo will use to generate the managed API.
portRequiredThe numeric port value that gets exposed via this endpoint.
typeRequiredThe type of traffic this endpoint is accepting, such as REST, GraphQL, gRPC, UDPor TCP. Currently, the MI preset supports only the REST type.
networkVisibilityRequiredThe network level visibility of this endpoint, which defaults to Public if not specified. Accepted values are Project, Organization, or Public.
contextRequiredThe context (base path) of the API that Choreo exposes via this endpoint.
schemaFilePathRequiredThe 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.
-

Sample endpoints.yaml

-

File location:

-
<docker-build-context-path>/.choreo/endpoints.yaml
-
- -
-

Note

-
    -
  • -

    For components built with Ballerina buildpack docker-build-context-path should be replaced with component-root. -For example: <component-root>/.choreo/endpoints.yaml

    -
    • -
  • -

    For components built with WSO2 MI buildpack docker-build-context-path should be replaced with <Project Path>. -For example: <Project Path>/.choreo/endpoints.yaml

    -
    • -
-
-

File content:

-
# +required Version of the endpoint configuration YAML
-version: 0.1
-
-# +required List of endpoints to create
-endpoints:
-  # +required Unique name for the endpoint. (This name will be used when generating the managed API)
-- name: Greeting Service
-  # +required Numeric port value that gets exposed via this endpoint
-  port: 9090
-  # +required Type of the traffic this endpoint is accepting. Example: REST, GraphQL, etc.
-  # Allowed values: REST, GraphQL, GRPC, UDP, TCP
-  type: REST
-  # +optional Network level visibility of this endpoint. Defaults to Public
-  # Accepted values: Project|Organization|Public.
-  networkVisibility: Project
-  # +optional Context (base path) of the API that is exposed via this endpoint.
-  # This is mandatory if the endpoint type is set to REST or GraphQL.
-  context: /greeting
-  # +optional Path to the schema definition file. Defaults to wild card route if not provided
-  # This is only applicable to REST endpoint types.
-  # The path should be relative to the docker context.
-  schemaFilePath: greeting_openapi.yaml
-
- -

Apply advanced component connection configurations

-

The component-config.yaml file extends the capabilities of endpoints.yaml by introducing enhancements that allow you to apply advanced inbound and outbound connection configurations.

-
-

Beta release

-
    -
  • The current version of the component-config.yaml file is considered stable. However, it is important to note that the configuration schema may undergo changes and improvements based on user feedback.
    • -
  • Support for the current schema will remain even when new versions are introduced.
    • -
-
-

The component-config.yaml file complements and enhances the existing endpoint configuration process. It allows you to define how your service's endpoints (inbound connections) are exposed and how your service connects to external services or components (outbound connections).

-
    -
  • -

    Inbound configurations: This configuration section is for you to define inbound connections, Similar to endpoints.yaml, you can define how your service endpoints are exposed. It aligns seamlessly with the existing endpoint schema structure.

    -
    • -
  • -

    Outbound configurations: This configuration section is for you to specify outbound connection details, including service connections. The Choreo Internal Marketplace facilitates creating connections with existing services. To learn more about Choreo Marketplace, see Choreo Marketplace.

    -
    • -
-
-

Note

-
    -
  • If both component-config.yaml and endpoints.yaml are defined in the .choreo path, the component-config.yaml file takes priority.
    • -
  • Outbound connections are not supported for deprecated components and WSO2 MI buildpack components.
    • -
-
-

Learn the component-config.yaml file

-

The component-config.yaml file has a specific structure and contains the following details:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldRequiredDescription
apiVersionRequiredThe version of the component-config.yaml file defaults to core.choreo.dev/v1beta1.
kindRequiredThe resource type of the file defaults to ComponentConfig.
spec.inboundOptionalThe list of inbound connection configurations.
spec.outboundOptionalThe list of outbound connection configurations.
-

Inbound connection configurations (spec.inbound)

-

In the spec.inbound configuration section, you can specify endpoints to set up inbound connections. To specify endpoints, you can follow the existing endpoints schema structure. For details on the endpoints schema structure, see the endpoints schema documentation.

-

Outbound connection configurations (spec.outbound)

-

In the spec.outbound section, you can define serviceReferences. To define serviceReferences, you can use the service references generated in the Internal Marketplace when creating a service connection. To copy the outbound connection configurations, see the inline developer guide that is available when you create a connection.

-

The serviceReferences schema has a specific structure and contains the following details:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldRequiredDescription
nameRequiredA unique name for the service reference.
connectionConfigRequiredA unique name for the connection instance.
envOptionalThe list of environment variable mappings that get injected into the container.
env.fromRequiredThe key name of the connection configuration.
env.toRequiredThe environment variable that gets injected into the container.
-
-

Note

-

Choreo automatically generates outbound connection configurations upon the creation of a connection within the internal marketplace. The properties such as name, connectionConfig, and env.from are automatically generated. However, you must manually set the env.to value.

-
-

Sample component-config.yaml

-

File location:

-
<docker-build-context-path>/.choreo/component-config.yaml
-
- -
-

Note

-
    -
  • For components built using the Ballerina buildpack, you must replace docker-build-context-path with the component-root. -For example, <component-root>/.choreo/component-config.yaml.
    • -
  • For components built using the WSO2 MI buildpack, you must replace docker-build-context-path with the <Project Path>. -For example, <Project Path>/.choreo/component-config.yaml.
    • -
-
-

File content:

-
apiVersion: core.choreo.dev/v1beta1
-kind: ComponentConfig
-spec:
-  # +optional Incoming connection details for the component (AKA endpoints).
-  inbound:
-    # +required Unique name for the endpoint. (This name will be used when generating the managed API)
-    - name: Greeting Service
-      # +required Numeric port value that gets exposed via the endpoint
-      port: 9090
-      # +required Type of traffic that the endpoint is accepting. For example: REST, GraphQL, etc.
-      # Allowed values: REST, GraphQL, GRPC, TCP, UDP.
-      type: REST
-      # +optional Network level visibility of the endpoint. Defaults to Public
-      # Accepted values: Project|Organization|Public.
-      networkVisibility: Public
-      # +optional Context (base path) of the API that gets exposed via the endpoint.
-      # This is mandatory if the endpoint type is set to REST or GraphQL.
-      context: /greeting
-      # +optional The path to the schema definition file. Defaults to wildcard route if not specified.
-      # This is only applicable to REST endpoint types.
-      # The path should be relative to the Docker context.
-      schemaFilePath: greeting_openapi.yaml
-  # +optional Outgoing connection details for the component.
-  outbound:
-    # +optional Defines the service references from the Internal Marketplace.
-    serviceReferences:
-      # +required Name of the service reference.
-      - name: choreo:///apifirst/mttm/mmvhxd/ad088/v1.0/PUBLIC
-        # +required Name of the connection instance.
-        connectionConfig: 19d2648b-d29c-4452-afdd-1b9311e81412
-        # +optional Environment variables injected to the component for connection configuration.
-        env:
-          # +required Key name of the connection configuration.
-          - from: ServiceURL
-            # +required Environment variable injected to the container.
-            to: SERVICE_URL
-
- -

Expose endpoints as managed APIs

-

Exposing endpoints as managed APIs is crucial to ensure secure and controlled access to the services being exposed. When a user wants to expose their written service to the outside world or to the organization at large, there is an inherent security risk involved. To mitigate this risk, the Choreo platform is built with an internal (access within the organization only) or external (publicly accessible) gateway that is protected with Choreo API management making the services secure by design.

-
-

Note

-

This feature is not available for gRPC, UDP, and TCP endpoints.

-
-

If you want to expose an endpoint as a managed API in Choreo, you need to set the network visibility to either Organization or Public. This allows the endpoint to be exposed through the Choreo API Gateway, which provides a number of benefits, including:

-
    -
  • Expose APIs to external and internal consumers
    • -
  • Full lifecycle API Management
    • -
  • API throttling
    • -
  • Secure APIs with industry-standard authorization flows
    • -
  • API analytics and monitoring
    • -
-

Once you deploy the service component, Choreo will expose the endpoint as a managed API through the Choreo API Gateway. You can then use the full lifecycle API management features provided by Choreo to test, deploy, maintain, monitor, and manage your API using the API management features.

-

Understand the default component URL

-

The default URL of a component corresponds to the default endpoint of the component and is structured as follows:

-

<domain>/<project-name>/<component-name>

-

This URL does not include the default endpoint name. For all other endpoints, the URL structure includes the endpoint name, as follows:

-

<domain>/<project-name>/<component-name>/<endpoint-name>

-

If a component has multiple endpoints, Choreo allows you to change the endpoint corresponding to the default component URL. For a component with a single endpoint, the default URL automatically corresponds to that endpoint.

-

Change the default endpoint of a component

-

To change the default endpoint of a component, follow the steps given below:

-
-

Note

-
    -
  • You cannot change the default endpoint if it has associated published APIs. You must go to the Lifecycle page and unpublish the relevant APIs before updating the default endpoint. For instructions on unpublishing an API, see Lifecycle Management.
    • -
  • Choreo does not allow you to change the default endpoint of a component if you create multiple deployment tracks within its current major version, or promote the component beyond its initial environment.
    • -
-
-
    -
  1. Sign in to the Choreo Console.
    2. -
  2. In the Component Listing pane, click on the component for which you want to change the default endpoint.
    3. -
  3. In the left navigation menu, click Deploy.
    4. -
  4. On the Deploy page, go to the Set Up card and click Configure & Deploy.
    5. -
  5. In the Environment Configurations pane that opens, click Next.
    6. -
  6. In the File Mount pane that opens, click Next.
    7. -
  7. In the Endpoint Details pane that opens, click the Default Endpoint list, select the endpoint you want to set as the default endpoint, and then click Update.
    8. -
  8. Click Deploy. This deploys the component with the selected endpoint as the default, and the default URL will now correspond to this endpoint.
    9. -
- - - - - - -
-
- - -
- - - -
- - -
- - - -
-
-
- - - - - - - - - - - - - - - - - \ No newline at end of file diff --git a/en/site/develop-components/configure-mutual-tls-between-components/index.html b/en/site/develop-components/configure-mutual-tls-between-components/index.html deleted file mode 100644 index 829b17d73..000000000 --- a/en/site/develop-components/configure-mutual-tls-between-components/index.html +++ /dev/null @@ -1,15 +0,0 @@ - - - - - - Redirecting... - - - - - - -Redirecting... - - diff --git a/en/site/develop-components/deploy-a-containerized-application/index.html b/en/site/develop-components/deploy-a-containerized-application/index.html deleted file mode 100644 index 9b9a2f698..000000000 --- a/en/site/develop-components/deploy-a-containerized-application/index.html +++ /dev/null @@ -1,3375 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - Deploy a Containerized Application - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- - - -
- - - - - - -
- - -
- -
- - - - - - - -
-
- - - -
-
-
- - - - -
-
-
- - - -
-
-
- - - -
-
-
- - - -
-
- - - - - - - - - - - - - - - - - - - - -

Deploy a Containerized Application

-

Using Choreo, you can easily deploy applications written in different language frameworks (such as Java, Go, NodeJS, Python, etc.) on shared or private data planes using containers.

-

Choreo supports deploying containerized applications for the following component types:

-
    -
  • Service
    • -
  • Web Application
    • -
  • Scheduled Task
    • -
  • Manual Task
    • -
  • Event Handler
    • -
  • Test Runner
    • -
-

Connect your repository to Choreo

-

To connect your GitHub repository to Choreo, you should authorize the Choreo Apps GitHub application to access your account or organization. When you attempt to connect your GitHub repository via the Component creation page, the Choreo Apps authorization prompt will appear.

-
    -
  • -

    Connect GitHub Repository

    -

    Connect GitHub Repository

    -
    • -
  • -

    Authorize GitHub Application

    -

    Authorize GitHub Application

    -
    • -
  • -

    Grant Repository Access

    -

    Grant Repository Access

    -

    The Choreo Apps requires the following permission:

    -
      -
    • Read access to issues and metadata
      • -
    • Read and write access to code, pull requests, and repository hooks
      • -
    -
    • -
-
-

Note

-

You can revoke access if you do not want Choreo to have access to your GitHub account. Choreo needs write access only to send pull requests to a user repository. Choreo does not directly push any changes to a repository.

-
-

Alternatively, you can connect a public repository without requiring authorization from the Choreo Apps GitHub application. You can paste a public repository URL in the Provide Repository URL field at the time of component creation.

-
-

Tip

-

Authorizing the repository with the Choreo Apps GitHub application becomes essential if you want to enable Auto Deploy for the component. If you own the repository, you can subsequently authorize it with the Choreo Apps GitHub application to enable Auto Deploy.

-
-

After granting access to the required repositories, you can choose a repository and an associated branch to connect to the Choreo component. -For the containerized application deployments, you should select the Dockerfile as the Buildpack and provide Dockerfile Path and Docker Context Path for the Docker build.

-

Connected Dockerfile Repository

-

The following table describes the individual fields in the Create Component pane.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldDescription
GitHub AccountYour GitHub account or organization. If you want to add another GitHub account, you can expand the list and click + Add.
GitHub RepositoryDepending on the repository access you provided, the list will show available repositories to be connected.
BranchThe branch of the repository.
BuildpackDetermines the implementation of the component: Any language or other language as a Docker container.
Dockerfile PathThe path to your Dockerfile. This path is defined relative to the repository root.
For example, if the Dockerfile is at the repository root, the value for this field is /Dockerfile.
Docker Context PathThe Docker build context path. To include the repository root, leave the default / value.
Port*The port at which your service is running.
OpenAPI Filepath*The path to an OpenAPI specification (in YAML/JSON) relative to the repository root. If you don't provide a path, the system automatically generates a default allow-all specification.
-
-

Note

-
    -
  • -

    Fields marked with * are not visible for all component types.

    -
    • -
  • -

    To successfully build your container with Choreo, it is essential to explicitly define a User ID (UID) under the USER instruction in your Dockerfile. You can refer to the sample Dockerfile for guidance.

    -
    • -
  • -

    To ensure that the defined USER instruction is valid, it must conform to the following conditions:

    -
      -
    • A valid User ID is a numeric value between 10000-20000, such as 10001 or 10500.
      • -
    • Usernames are not considered valid and should not be used. For example, my-custom-user-12221 or my-custom-user are invalid User IDs.
      • -
    -
    • -
-
-

Deploy the containerized component

-

Choreo will automatically apply deployment configurations and settings based on the component type you select during creation. -For example, if you select the Service component type, Choreo will deploy it as a Kubernetes deployment with appropriate scaling configurations.

-

You can run unit tests in the build pipeline by adding the relevant command to the Dockerfile. For example:

- -

Application configurations

-

You must provide any required configurations for running the application in the Configs & Secrets section of the component's DevOps page. Alternatively, you can also review the configurations when you manually deploy via the Deploy page.

-

After clicking the Create button, you can select the confidentiality of the configuration and specify how to mount it to the container.

-

Application Configuration Page

-

Create Configuration Mount Page

-

Configuration types

-
    -
  • ConfigMap: Stores non-confidential data as key-value pairs.
    • -
  • Secret: Stores and manages sensitive information, such as passwords, OAuth tokens, and ssh keys as key-value pairs.
    • -
-

Mount types

-
    -
  • Environment Variables: Mounts the selected ConfigMap or Secret as an environment variable in the container.
    • -
  • File Mount: Mounts the selected ConfigMap or Secret as a file in the container. Here, the key is the file name, and the value is the file content.
    • -
-

The following image shows adding a ConfigMap with File Mount mount type to be read by the application.

-

Configuration File Mount Page

-
-

Note

-

The JSON file includes ${DB_PASS} as an environment variable defined in a Secret. The application reads the JSON file and substitutes the placeholders with the corresponding environment variables.

-
-

Deployment configurations

-

Choreo lets you configure deployment settings such as scaling, resource limits, and health checks based on your selected component type.

-

For more information about these configurations, see Choreo's DevOps capabilities.

-

You can configure the Endpoints to expose your service using the Service Component in Choreo. See Service Component Overview for more information.

-

Build, deploy, and promote

-

After adding the application configuration, you can build and deploy it by clicking the Deploy Manually button. Choreo will start the build process with the selected commit in the Build Area.

-
-

Note

-

The Auto Deploy on Commit feature, which automatically builds and deploys the application upon pushing a code change to the repository, is enabled by default. To turn off this feature, navigate to the Build Area of the Deploy page.

-
-

Choreo scans your Dockerfile for security vulnerabilities during the build phase, and if there are no issues found, it proceeds with the build process. After building the image, it scans it again for vulnerabilities before deployment to the environment. You can view the build logs from the right-side panel, as shown in the image below.

-

Build Logs Panel

-

Once the build process is complete, Choreo will deploy the application automatically to the Development environment. To promote the build to higher environments, you can click the Promote button. The number of environment cards visible on the page may vary depending on your environment configurations.

-

Troubleshoot security vulnerability scan failures (Trivy)

-

By default, Choreo utilizes the Aqua Trivy (OSS) image vulnerability scanner to detect security vulnerabilities in all Dockerfile-based build pipelines. The scanner will fail the pipeline if any CRITICAL CVEs (Common Vulnerabilities and Exposures) are detected. CVEs of other severity levels are recorded but does not fail the pipeline.

-

If you cannot fix a critical CVE immediately, you can opt to ignore it. To ignore a critical CVE, add a trivyignore (<docker-build-context-path>/.trivyignore) file to your build context path. In the file, add the CVEs you need the pipeline to ignore, one entry per line as follows:

-
CVE-2023-xxxx
-CVE-2023-yyyy
-
- -

You can add comments in the file by using # in front of the comment as follows:

-
# comments can be added like this
-CVE-2023-xxxx
-
- - - - - - -
-
- - -
- - - -
- - -
- - - -
-
-
- - - - - - - - - - - - - - - - - \ No newline at end of file diff --git a/en/site/develop-components/deploy-an-application-with-buildpacks/index.html b/en/site/develop-components/deploy-an-application-with-buildpacks/index.html deleted file mode 100644 index 46f9f4958..000000000 --- a/en/site/develop-components/deploy-an-application-with-buildpacks/index.html +++ /dev/null @@ -1,3521 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - Deploy an Application with Buildpacks - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- - - -
- - - - - - -
- - -
- -
- - - - - - - -
-
- - - -
-
-
- - - - -
-
-
- - - -
-
-
- - - -
-
-
- - - -
-
- - - - - - - - - - - - - - - - - - - - -

Deploy an Application with Buildpacks

-

Using Choreo, you can easily deploy applications written in different language frameworks (such as Java, Go, NodeJS, Python, Ruby, PHP, etc.) on shared or private data planes.

-

Choreo supports deploying applications with buildpacks for the following component types:

-
    -
  • Service
    • -
  • Web Application
    • -
  • Scheduled Task
    • -
  • Manual Task
    • -
  • Webhook
    • -
  • Event Handler
    • -
  • Test Runner
    • -
-

Buildpacks

-

Buildpacks are a fundamental building block in modern application development. They convert your source code into a secure, efficient, production-ready container image without a Dockerfile. With Choreo, developers can take advantage of this powerful tool to effortlessly deploy their applications without the hassle of manual configuration.

-

Choreo uses Google Buildpacks as default buildpacks for Java, Go, NodeJS, Python, PHP, and Ruby. Choreo uses its own buildpacks for Ballerina and WSO2 MI.

-

Develop a component

-

To develop a service component that exposes a Service in Go, you can follow the Develop a Service guide.

-

Follow the guidelines below based on your language:

-
-
-
-

Supported Versions - 3.10.x, 3.11.x

-

Refer below examples for different component types. Follow the readme.md inside the example.

- - - - - - - - - - - - - - - - - -
Component TypeExample
ServiceReading Books List Service
Manual TaskHello World Task
-

Procfile

-

A Procfile is a configuration file used to declare the commands that are run by your application's containers.

-
-

Info

-

In Python projects, it is mandatory to have a Procfile with the web process type in the project root directory.

-
-

Here's an example Procfile for an application:

-
web: <command to start your application>
-
- -

e.g.,

-

web: python main.py
-web: gunicorn --bind :8080 --workers 1 --threads 8 --timeout 0 main:app
-web: flask run --host=0.0.0.0

-

For more examples, see Choreo samples.

-
-
-

Supported Versions - 2201.3.5, 2201.4.1, 2201.5.0, 2201.5.1, 201.6.0, 2201.7.0

-

Refer below examples for different component types. Follow the readme.md inside the example.

- - - - - - - - - - - - - - - - - - - - - - - - - -
Component TypeExample
ServiceEcho Service
Manual TaskCovid19 Statistics To Email
WebhookSalesforce New Case To Google Sheet
Scheduled TaskShopify New Customers to HubSpot Create/Update Contact
-

For more examples, see Choreo samples.

-
-
-

Supported Versions - 1.x

-

Refer below examples for different component types. Follow the readme.md inside the example.

- - - - - - - - - - - - - - - - - - - - - -
Component TypeExample
ServiceGreeting Service
Manual TaskHello World Task
Web ApplicationHello World Web Application
-

For more examples, see Choreo samples.

-
-
-

Supported Versions - 6.x, 7.x, 8.x

-

Refer below examples for different component types. Follow the readme.md inside the example.

- - - - - - - - - - - - - -
Component TypeExample
ServiceGreeting Service
-

For more examples, see Choreo samples.

-
-
-

Supported Versions - - 8, 11, 17, 18 (OpenJDK Runtime Environment Temurin)

-

Refer below examples for different component types. Follow the readme.md inside the example.

- - - - - - - - - - - - - - - - - -
Component TypeExample
ServiceProduct Management Service
Manual TaskHello World Task
-
-

Info

-

When working on Java projects:

-
    -
  • The Main class should be defined in the manifest file.
    • -
  • If Maven files such as mvn.cmd exist in the project without the .mvn directory, the build will fail. To ensure a successful build, you must either commit the .mvn directory along with any Maven files or not include any Maven files in the project if you choose not to commit the .mvn directory.
    • -
-
-

Procfile

-

A Procfile is a configuration file used to declare the commands that are run by your application's containers. -If you want to customize the default entry point of the container, you can include a Procfile with the web process type in the project root directory. -In Java projects, it is optional to include a Procfile.

-

Here's an example Procfile for an application:

-
web: <command to start your application>
-
- -

e.g.,

-

web: java -jar target/sample.jar

-

For more examples, see Choreo samples.

-
-
-

Supported Versions - 12.x.x, 14.x.x, 16.x.x, 18.x.x, 20.x.x

-

Refer below examples for different component types. Follow the readme.md inside the example.

- - - - - - - - - - - - - - - - - -
Component TypeExample
ServiceReading Books List Service
Manual TaskHello World Task
-

Procfile

-

A Procfile is a configuration file used to declare the commands that are run by your application's containers. -If you want to customize the default entry point of the container, you can include a Procfile with the web process type in the project root directory. -In NodeJS projects, it is optional to include a Procfile.

-

Here's an example Procfile for an application:

-
web: <command to start your application>
-
- -

e.g.,

-

web: node app.js

-

For more examples, see Choreo samples.

-
-
-

Supported Versions - 8.1.x, 8.2.x

-

Refer below examples for different component types. Follow the readme.md inside the example.

- - - - - - - - - - - - - - - - - - - - - -
Component TypeExample
ServiceHello World Service
Manual TaskHello World Task
Web ApplicationHello World Web Application
-

Procfile

-

A Procfile is a configuration file used to declare the commands that are run by your application's containers. -If you want to customize the default entry point of the container, you can include a Procfile with the web process type in the project root directory. -In PHP projects, it is optional to include a Procfile.

-

Here's an example Procfile for an application:

-
web: <command to start your application>
-
- -

e.g.,

-

web:php -S 0.0.0.0:8000 index.php

-

For more examples, see Choreo samples.

-
-
-

Supported Versions - 3.1.x, 3.2.x

-

Refer below examples for different component types. Follow the readme.md inside the example.

- - - - - - - - - - - - - - - - - - - - - -
Component TypeExample
ServiceHello World Service
Manual TaskHello World Task
Web ApplicationHello World Web Application
-

Procfile

-

A Procfile is a configuration file used to declare the commands that are run by your application's containers. -If you want to customize the default entry point of the container, you can include a Procfile with the web process type in the project root directory. -In Ruby projects, it is optional to include a Procfile.

-

Here's an example Procfile for an application:

-
web: <command to start your application>
-
- -

e.g.,

-

web: ruby app.rb
-web:bundle exec ruby app.rb -p 8080

-

For more examples, see Choreo samples.

-
-
-

Supported Versions - 4.1.0.x, 4.2.0.x

-

Refer below examples for different component types. Follow the readme.md inside the example.

- - - - - - - - - - - - - -
Component TypeExample
ServiceHello World Service
-

For more examples, see Choreo samples.

-
-
-

Supported Java Versions - - 8, 11, 17, 18 (OpenJDK Runtime Environment Temurin)

-
-

Info

-

You can use this buildpack only with web applications. For other component types, use the Java buildpack. Additionally, if the generated artifact is a WAR file, it is necessary to include a Procfile.

-
-

Procfile

-

A Procfile is a configuration file used to declare the commands that are run by your application's containers. -If you want to customize the default entry point of the container, you can include a Procfile with the web process type in the project root directory. -In Java projects, it is optional to include a Procfile.

-

Here's an example Procfile for an application:

-
web: <command to start your application>
-
- -

e.g.,

-

web: java -jar target/sample.war

-
-
-
-

Configure build-time environment variables

-

You can configure the environment variables necessary to build the component using the Build Configurations Editor on the component Build page.

-
-

Info

-

The capability to configure build-time environment variables is not available for components created using Ballerina or WSO2 MI buildpacks.

-
-

During the build process, the build-time environment variables and their values are passed to the buildpack. Therefore, you can configure both buildpack-specific environment variables and those required for the component build.

-

For example, if you want to override the Maven command of the Java buildpack, you can use GOOGLE_MAVEN_BUILD_ARGS as the environment key and clean install as the value.

-

For more examples, see Google Cloud's buildpacks documentation.

- - - - - - -
-
- - -
- - - -
- - -
- - - -
-
-
- - - - - - - - - - - - - - - - - \ No newline at end of file diff --git a/en/site/develop-components/develop-a-rest-api-proxy/index.html b/en/site/develop-components/develop-a-rest-api-proxy/index.html deleted file mode 100644 index 0382539cc..000000000 --- a/en/site/develop-components/develop-a-rest-api-proxy/index.html +++ /dev/null @@ -1,15 +0,0 @@ - - - - - - Redirecting... - - - - - - -Redirecting... - - diff --git a/en/site/develop-components/develop-a-web-application/index.html b/en/site/develop-components/develop-a-web-application/index.html deleted file mode 100644 index 0a05f6185..000000000 --- a/en/site/develop-components/develop-a-web-application/index.html +++ /dev/null @@ -1,15 +0,0 @@ - - - - - - Redirecting... - - - - - - -Redirecting... - - diff --git a/en/site/develop-components/develop-a-webhook/index.html b/en/site/develop-components/develop-a-webhook/index.html deleted file mode 100644 index 569bb0bcc..000000000 --- a/en/site/develop-components/develop-a-webhook/index.html +++ /dev/null @@ -1,3423 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - Develop a Webhook - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- - - -
- - - - - - -
- - -
- -
- - - - - - - -
-
- - - -
-
-
- - - - -
-
-
- - - -
-
-
- - - -
-
-
- - - -
-
- - - - - - - - - - - - - - - - - - - - -

Develop a Webhook

-

Choreo allows developers to design high-quality webhooks. To explore this capability, let's consider a scenario where a team of software engineers in an organization should be notified via email whenever someone creates a GitHub issue with the bug label in a specific repository.

-

In this tutorial, you will address the requirement by doing the following:

-
    -
  • Create a webhook by connecting to a forked GitHub repository where you have the webhook implementation that addresses the described requirement.
    • -
  • Deploy the webhook to the development environment.
    • -
  • Modify the webhook implementation to connect the webhook to GitHub, enabling it to act in response to selected GitHub-related events.
    • -
  • Test the webhook.
    • -
  • Promote the webhook to the production environment.
    • -
-

Prerequisites

-

Before you try out the steps in this guide, complete the following:

-
    -
  • -

    If you are signing in to the Choreo Console for the first time, create an organization as follows:

    -
      -
    1. Go to https://console.choreo.dev/, and sign in using your preferred method.
      2. -
    2. Enter a unique organization name. For example, Stark Industries.
      3. -
    3. Read and accept the privacy policy and terms of use.
      4. -
    4. Click Create. - This creates the organization and opens the Project Home page of the default project created for you.
      5. -
    -
    • -
  • -

    Fork the Choreo samples repository, which contains the sample integration for this guide.

    -
    • -
-

Step 1: Create a Webhook component

-

To create a project, add a Webhook component to it, design the webhook, test it, and then commit it to make it available in the Choreo Console, follow these sub-steps:

-

First, let's create a Webhook component as follows:

-
    -
  1. Go to https://console.choreo.dev/, and sign in using your preferred method.
    2. -
  2. If you already have one or more components in your project, click + Create. Otherwise, proceed to the next step.
    3. -
  3. Go to the Webhook card and click Create.
    4. -
  4. This opens the Create a Webhook pane, where you can specify a name and description for the component. Enter a unique name and description.
    5. -
  5. Go to the GitHub tab.
    6. -
  6. -

    To allow Choreo to connect to your GitHub account, click Authorize with GitHub. If you have not already connected your GitHub repository to Choreo, enter your GitHub credentials and select the repository you created in the prerequisites section to install the Choreo GitHub App.

    -

    Alternatively, you can paste the Choreo samples repository URL in the Provide Repository URL field to connect to it without requiring authorization from the Choreo Apps GitHub application. However, authorizing the repository with the Choreo GitHub App is necessary if you want to enable Auto Deploy for the component.

    -
    -

    Note

    -

    The Choreo GitHub App requires the following permissions:

    -
      -
    • Read and write access to code and pull requests.
      • -
    • Read access to issues and metadata.
      • -
    -

    You can revoke access if you do not want Choreo to have access to your GitHub account. However, write access is exclusively utilized for sending pull requests to a user repository. Choreo will not directly push any changes to a repository.

    -
    -
    7. -
  7. -

    Select the Access Mode depending on your requirement.

    -
    8. -
  8. -

    Enter the following information:

    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    FieldDescription
    GitHub AccountYour account
    GitHub Repositorychoreo-samples
    Branchmain
    BuildpackBallerina
    Project Pathgithub-event-to-email-webhook
    -
    9. -
  9. -

    Click Create.

    -
    10. -
-

Choreo creates the Webhook component with the sample implementation and opens the component Overview page.

-

Step 2: Deploy

-

Let's deploy the webhook to the development environment to make it invokable:

-
    -
  1. In the Choreo Console left navigation menu, click Deploy.
    2. -
  2. In the Build Area card, click Configure & Deploy.
    3. -
  3. -

    In the Configurations pane, enter the following information:

    -
      -
    1. -

      In the webhookSecret field, enter any value.

      -
      -

      Note

      -

      You must save this value for later use.

      -
      -
      2. -
    2. -

      In the toEmail field, enter the email address to send notification emails.

      -
      3. -
    3. Click Deploy.
      4. -
    -

    You can monitor the deployment progress in the Console pane that opens on the right of the page.

    -
    4. -
-

Once Choreo completes the deployment, the Development card indicates the Deployment Status as Active.

-
-

Notes

-

In the deployment card, you can click the icon corresponding to configurables to open the Configurations pane and edit configurations:

-
-

Step 3: Connect the webhook to the GitHub repository

-

To allow the webhook to read the labels of issues in a specific GitHub repository, you must connect the webhook to the GitHub repository. To do this, follow these steps:

-
    -
  1. -

    In the Choreo Console left navigation menu, click Overview.

    -
    2. -
  2. -

    On the Overview page, copy the invoke URL. You can click the copy icon within the URL field.

    -
    3. -
  3. -

    Go to your GitHub account and open the repository for which you want to generate notification emails.

    -
    4. -
  4. -

    In the top menu, click the Settings tab.

    -
    5. -
  5. -

    In the left navigation menu, click Webhooks.

    -
    6. -
  6. -

    Click Add webhook and enter the following information:

    - - - - - - - - - - - - - - - - - - - - - -
    FieldValue
    Payload URLThe invoke URL you copied in Step 3, sub-step 1.
    Content TypeSelect application/json
    SecretThe last webhook secret you configured in Step 2.
    -
    -

    Tip

    -
      -
    • -

      Buildpack specifies the type of build to run depending on the implementation of the component. It converts the integration code into a Docker image that can run on Choreo cloud. If an integration is developed using WSO2 Integration Studio, select Micro Integrator as the buildpack. If an integration is developed using the Ballerina language, select Ballerina as the buildpack.

      -
      • -
    • -

      Project Path specifies the location of the project to build the component.

      -
      • -
    -
    -
    7. -
  7. -

    Under Which events would you like to trigger this webhook?, select Let me select individual events.

    -
    8. -
  8. -

    Select the Issues checkbox in the list of events displayed.

    -

    By doing so, you select GitHub issues as events that need to trigger this webhook.

    -
    9. -
  9. -

    In the same list of events, clear the Pushes checkbox to ensure that GitHub does not trigger your webhook when the team pushes changes to the selected GitHub repository.

    -
    10. -
  10. -

    Click Add webhook to save the configuration.

    -
    11. -
-

Now you have integrated Choreo with GitHub via the webhook you created and deployed. You can proceed to test the webhook.

-

Step 4: Test

-

To test your webhook, create a GitHub issue with the Bug label in the repository that you connected to the webhook.

-

You will receive a mail similar to the following to the email address you provided in Step 2.

-

Step 5: Promote

-

To promote the webhook to the Production environment, follow these steps:

-
    -
  1. -

    On the Deploy page, go to the Development card and click Promote.

    -
    2. -
  2. -

    In the Configuration Types pane, leave the default selection (i.e., Use default configuration values) unchanged.

    -

    If you have configured any default values for the configurable variables, selecting Use default configuration values allows you to proceed with those values.

    -

    If you have not configured any default values for configurable variables, follow the steps given below to specify values.

    -
    3. -
  3. -

    Click Next.

    -
    4. -
  4. -

    In the webhookSecret field, enter any value.

    -
    -

    Note

    -

    You must save this value for later use.

    -
    -
    5. -
  5. -

    In the toEmail field, enter the email address to send notification emails.

    -
    6. -
  6. Click Promote.
    7. -
-

Once the component is promoted to production, the Production card displays the deployment status as Active.

-

Now you have successfully created, deployed, and tested a Webhook component and promoted it to production.

- - - - - - -
-
- - -
- - - -
- - -
- - - -
-
-
- - - - - - - - - - - - - - - - - \ No newline at end of file diff --git a/en/site/develop-components/develop-an-api-proxy/index.html b/en/site/develop-components/develop-an-api-proxy/index.html deleted file mode 100644 index 49b99dd24..000000000 --- a/en/site/develop-components/develop-an-api-proxy/index.html +++ /dev/null @@ -1,3477 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - Develop an API Proxy - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- - - -
- - - - - - -
- - -
- -
- - - - - - - -
-
- - - -
-
-
- - - - -
-
-
- - - -
-
-
- - - -
-
-
- - - -
-
- - - - - - - - - - - - - - - - - - - - -

Develop an API Proxy

-

An API proxy acts as an intermediary between an existing API and Choreo, intercepting all requests made to the API. It also functions as a managed API, which allows you to apply essential API management features such as security policies and rate limiting.

-

In this guide, you will:

-
    -
  • Create an API proxy component to expose an existing API.
    • -
  • Deploy the API proxy.
    • -
  • Test the API proxy to verify its functionality.
    • -
  • Manage the API.
    • -
  • Consume the API.
    • -
-

Prerequisites

-

Before you try out this guide, complete the following:

-
    -
  • -

    If you are signing in to the Choreo Console for the first time, create an organization as follows:

    -
      -
    1. Go to https://console.choreo.dev/, and sign in using your preferred method.
      2. -
    2. Enter a unique organization name. For example, Stark Industries.
      3. -
    3. Read and accept the privacy policy and terms of use.
      4. -
    4. Click Create.
      5. -
    -

    This creates the organization and opens the Project Home page of the default project created for you.

    -
    • -
-

Step 1: Create an API proxy

-

To create an API proxy, you can either upload an OpenAPI specification or provide an OpenAPI specification URL. In this guide, you will specify a URL to an OpenAPI definition of a sample API.

-

Follow the steps given below:

-
    -
  1. Go to https://console.choreo.dev/ and sign in. This opens the project home page.
    2. -
  2. If you already have one or more components in your project, click + Create. Otherwise, proceed to the next step.
    3. -
  3. Click the API Proxy card. - This opens the Create an API Proxy pane, where you can upload an OpenAPI definition or provide the URL of an OpenAPI. In this guide, you will define resources manually. Therefore, click Skip Source to proceed.
    4. -
  4. -

    Specify the values given in the following table as API proxy details:

    -
    -

    Info

    -

    In the Name field, you must specify a name to uniquely identify the component in various contexts. The value is editable only at the time you create the component. You cannot change the name after you create the component.

    -
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    FieldValue
    Display NameHR API
    Namehr-api
    Contextabc-hr
    Version1.0
    Targethttps://samples.choreoapps.dev/company/hr
    Access ModeExternal
    -
    5. -
  5. -

    Click Create.

    -
    6. -
-

This creates the API proxy component and takes you to the Overview page. Now you can proceed to define resources for the API proxy.

-

Step 2: Define resources for the API proxy

-

To add a new resource that can retrieve a department by the department ID, follow the steps given below:

-
    -
  1. In the left navigation menu, click Develop and then click Resources.
    2. -
  2. Select GET as the HTTP Verb and enter /department/{departmentId} as the URI Pattern.
    3. -
  3. Click + to add the resource.
    4. -
  4. -

    Click to expand the added resource and specify appropriate values for the Operation ID and Description fields. You can specify the values given in the following table:

    - - - - - - - - - - - - - - - - - -
    FieldValue
    Operation IDfindDepartment
    DescriptionFind a department by department ID
    -
    5. -
  5. -

    To remove the five default resources that start with /*, click the delete icon corresponding to each resource. This marks the resources for deletion.

    -
    6. -
  6. Click Save.
    7. -
-

Step 3: Deploy the API proxy

-

To deploy the API proxy to the development environment, follow the steps given below:

-
    -
  1. -

    In the left navigation menu, click Deploy.

    -
    2. -
  2. -

    In the Build Area card, click Configure & Deploy. This opens the Configure & Deploy pane, where you can select the API access mode depending on how you want the API to be accessible. Here, you can select External.

    -
    3. -
  3. -

    Click Deploy. The Development card indicates the Deployment Status as Active when the API proxy is successfully deployed.

    -
    4. -
-

Now you are ready to test the API proxy.

-

Step 3: Test the API proxy

-

Choreo allows you to test your API proxy using either the integrated OpenAPI Console or cURL.

-

In this guide, you will use the OpenAPI Console to test the API proxy.

-

Follow the steps given below:

-
-

Tip

Choreo enables OAuth 2.0 to secure APIs by default. Therefore, you need an access token to invoke an API.

-
    -
  • Choreo automatically generates a key to test the API via the OpenAPI Console. To view the key, click the show key icon in the Security Header field.
    • -
  • Choreo allows you to disable security for an entire API or a specific API resource for testing purposes. If you want to disable security, follow these steps:
      -
    1. In the left navigation menu, click Deploy.
      2. -
    2. Go to the Build Area card and click Security Settings.
      3. -
    3. In the Security Settings pane, perform one of the following actions depending on your requirement:
        -
      • To disable security for the entire API, clear the OAuth2 checkbox.
        • -
      • To disable security for a specific API resource, go to the Permissions section, click to expand the relevant resource and then turn off the Security toggle.
        • -
      -
      4. -
    4. Click Apply.
      5. -
    -
    • -
-

-
-
    -
  1. -

    In the left navigation menu, click Test and then click OpenAPI Console.

    -
    2. -
  2. -

    Select Development from the environment drop-down list.

    -
    3. -
  3. -

    Expand the GET /department/{departmentId} resource and click Try it Out to test it.

    -
    4. -
  4. -

    Enter 1 as the departmentId and click Execute. You will see a response similar to the following:

    -

    API proxy response

    -
    5. -
-

This indicates that your API proxy is working as expected.

-

Step 4: Manage the API proxy

-

Now that you have a tested API proxy, you can publish it and make it available for application developers to consume. Depending on your requirement, you can apply security, throttling, and other settings to the API before you publish it.

-

In this guide, you will apply rate limiting to the API and publish it.

-

Step 4.1: Apply a rate limiting level to the API proxy

-

To apply a rate limiting level to the API, follow the steps given below:

-
    -
  1. In the left navigation menu, click Deploy.
    2. -
  2. Go to the required environment card and click the setting icon corresponding to API Configuration.
    3. -
  3. In the API Configuration pane that opens, click Rate Limiting to expand the section.
    4. -
  4. Select API Level as the Rate Limiting Level.
    5. -
  5. Specify appropriate values for the Request Limit and Time Unit fields. In this guide, you can proceed with the default values. - This applies a rate-limiting policy to the entire API. If necessary, you can also apply rate limits at the operation level. For more information, see API Rate Limiting.
    6. -
  6. Click Apply. This applies the rate limiting level to the API proxy and redeploys it.
    7. -
-

Step 4.2: Publish the API proxy

-

To publish the API proxy to the Choreo Developer Portal, follow the steps given below:

-
    -
  1. In the left navigation menu, click Lifecycle under Manage. This takes you to the Lifecycle page where you can see the different lifecycle stages the API can be in. You can see that the current lifecycle stage is Created.
    2. -
  2. Click Publish.
    3. -
  3. In the Publish API dialog that opens, click Confirm to proceed publishing the API with the specified display name. If you want to change the display name, make the necessary changes and then click Confirm. This changes the API lifecycle state to Published.
    4. -
-

Step 5: Invoke the API

-

To generate credentials for the published API and to invoke it via the Choreo Developer Portal, follow the steps below:

-
    -
  1. -

    To open the published API in the Choreo Developer Portal via the Lifecycle page, click Go to Devportal. This takes you to the HR API in the Choreo Developer Portal.

    -
    2. -
  2. -

    To generate credentials to test the API, follow the steps given below:

    -
      -
    1. In the Developer Portal left navigation menu, click Production under Credentials.
      2. -
    2. -

      Click Generate Credentials. Choreo generates new tokens and populates the Consumer Key and Consumer Secret fields.

      -
      -

      Tip

      -

      If you want to test the API via an API test tool or through code, click Generate Access Token and copy the test token that is displayed. Alternatively, click cURL and copy the generated cURL command to use via a cURL client. You do not need to generate an access token if you are testing the API via the Try Out capability in the Choreo Developer Portal.

      -
      -
      3. -
    -
    3. -
  3. -

    To invoke a resource via the Try Out capability in the Choreo Developer Portal, follow the steps given below:

    -
      -
    1. In the Developer Portal left navigation menu, click Try Out.
      2. -
    2. In the Endpoint list, select Development as the environment to try out the API.
      3. -
    3. To generate an access token to try out the API, click Get Test Key. This populates the Access Token field with a test key.
      4. -
    4. Expand the GET /department/{departmentId} resource and click Try it out.
      5. -
    5. -

      Enter 1 as the departmentId and click Execute. You will see a response similar to the following:

      -

      Try out response

      -
      6. -
    -
    4. -
-

Now, you have gained hands-on experience creating, deploying, testing, and publishing an API proxy using Choreo API Manager.

-

To learn more about the API management capabilities supported by Choreo API Manager, see API Management.

- - - - - - -
-
- - -
- - - -
- - -
- - - -
-
-
- - - - - - - - - - - - - - - - - \ No newline at end of file diff --git a/en/site/develop-components/develop-components-using-vs-code/index.html b/en/site/develop-components/develop-components-using-vs-code/index.html deleted file mode 100644 index d6431a3d7..000000000 --- a/en/site/develop-components/develop-components-using-vs-code/index.html +++ /dev/null @@ -1,3307 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - Develop Components Using VS Code - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- - - -
- - - - - - -
- - -
- -
- - - - - - - -
-
- - - -
-
-
- - - - -
-
-
- - - -
-
-
- - - -
-
-
- - - -
-
- - - - - - - - - - - - - - - - - - - - -

Develop Components Using VS Code

-

The Choreo VS Code extension provides comprehensive component management capabilities to streamline local development within Choreo.

-

Prerequisites

-

To ensure a smooth development experience with the Choreo extension, make sure you have the following:

-
    -
  1. -

    Visual Studio Code installed with the Choreo extension version 2.0.0 or later.

    -
    2. -
  2. -

    A locally cloned GitHub repository to create new components or link to existing Choreo components.

    -
    3. -
  3. -

    Git version 2.0.0 or later.

    -
    4. -
-

Get started

-

To use the capabilities of the Choreo extension in the VS Code editor, you need an active Choreo account. If you already have an account, follow these steps to set up the extension:

-
    -
  1. Install the Choreo VS Code extension and wait for activation. On successful activation, the Choreo extension opens in the VS Code editor.
    2. -
  2. -

    Sign in to Choreo using one of the following methods:

    -
      -
    • In the Choreo activity pane, click Sign In. - Sign in
      • -
    • Use the Sign In command provided by the Choreo extension.
      • -
    -

    This redirects you to an external URI to complete the authentication process. On successful sign-in, the Choreo activity pane displays your account details along with any components detected within the VS Code workspace.

    -
    3. -
-

Create a new component

-
    -
  1. Open the source code directory where you want to build, deploy, and manage components using Choreo.
    2. -
  2. -

    Create a new component using one of the following methods:

    -
      -
    • In the Choreo activity pane, click Create Component. - Create Component Button
      • -
    • Use the Create New Component command provided by the Choreo extension.
      • -
    -
    3. -
  3. -

    If the Choreo extension cannot determine the project context of the opened workspace, it prompts you to select the organization and the project to which the new component belongs.

    -
    4. -
  4. -

    Specify component details such as the name, type, buildpack, etc.

    -

    Component Form

    -

    On successful creation, the component details view opens, and the Choreo activity pane displays the new component.

    -

    Component Details

    -
    -

    Tip

    -

    Once the component is created, a .choreo/context.yaml file is generated in the root of the Git repository. For more details, see Understand the project context.

    -
    -
    5. -
-

The component details view allows you to manage your component by performing various actions such as the following:

-
    -
  • Triggering builds for selected commits.
    • -
  • Viewing lists of builds and statuses.
    • -
  • Diagnosing build failures with build logs.
    • -
  • Deploying builds in available environments.
    • -
  • Accessing runtime logs and deployed component URLs.
    • -
  • Invoking deployed service endpoints.
    • -
-

Understand the project context

-

Context files contain metadata related to the project, allowing the extension to establish an association between local directories and Choreo projects. These files, such as the context.yamlfile, resides in the /.choreo directory within the root of the Git repository.

-

The Choreo extension scans the root of the opened Git repository to find the context.yaml file and lists the components of the associated project. This allows you to easily open and manage the components they are developing within the VS Code workspace.

-

A context.yaml file can contain multiple projects, whereas, a workspace opened via VS Code can have multiple context.yaml files with different project associations. In such cases, VS Code allows you to switch between these projects, add new project associations, or remove existing ones, allowing you as a developer to focus on components of a particular project at a time.

-

You can decide whether to commit the context.yaml file to the Git repository. Committing this file enables other team members working on the same repository to have a seamless developer experience with Choreo.

-

If the context.yaml file for a particular project is not committed to the Git repository or is unavailable for other reasons, you can easily regenerate it using one of the following methods:

-
    -
  • In the Choreo activity pane, click Link Directory. - Link Directory
    • -
  • Use the Link Directory command provided by the Choreo extension.
    • -
-

Discover additional features

-

To access a range of functionalities provided by the Choreo extension, open the VS Code command palette and type Choreo.

-

Troubleshoot issues

-

To troubleshoot Choreo extension issues, follow these steps:

-
    -
  1. -

    To open the OUTPUT pane, go to the VS Code editor main menu, click View, and then click Output.

    -
    2. -
  2. -

    Select Choreo from the drop-down menu on the right-hand side to view the Choreo output for troubleshooting.

    -
    3. -
-

Get help

-

For assistance with the Choreo VS Code extension, create GitHub issues.

- - - - - - -
-
- - -
- - - -
- - -
- - - -
-
-
- - - - - - - - - - - - - - - - - \ No newline at end of file diff --git a/en/site/develop-components/develop-components-with-git/index.html b/en/site/develop-components/develop-components-with-git/index.html deleted file mode 100644 index b3101bc44..000000000 --- a/en/site/develop-components/develop-components-with-git/index.html +++ /dev/null @@ -1,3362 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - Develop Components With Git - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- - - -
- - - - - - -
- - -
- -
- - - - - - - -
-
- - - -
-
-
- - - - -
-
-
- - - -
-
-
- - - -
-
-
- - - -
-
- - - - - - - - - - - - - - - - - - - - -

Develop Components With Git

-

Choreo enables you to develop components by connecting your GitHub, Bitbucket, or GitLab repository. You have the flexibility to either connect an existing repository or start with an empty repository and commit the source code later. By integrating your repositories with Choreo, you can automate tasks and optimize workflows across multiple systems, all within the Choreo platform. Choreo currently supports GitHub, Bitbucket, and GitLab as Git providers.

-
-

Tip

-

Choreo supports both Bitbucket Server and Bitbucket Cloud. The currently supported Bitbucket Server version is 8.9.2.

-
-

In Choreo, you can connect a Git repository that contains Ballerina source code or a Docker project. To connect a Git repository to Choreo as a Docker project, your Git repository must include the following:

-
    -
  • A Dockerfile: Specifies the instructions to build the Docker image.
    • -
  • A build context: A set of files in the specified path used to build the image.
    • -
-

Once you connect your Git repository to Choreo, you can build, deploy, and manage your application easily.

-

Connect a Git repository to Choreo

-
    -
  1. Sign in to the Choreo Console.
    2. -
  2. In the Choreo Console header, go to the Organization list and select your organization.
    3. -
  3. In the left navigation menu, click Settings. This opens the organization-level settings page.
    4. -
  4. Click the Credentials tab.
    5. -
  5. Click +Add Credentials to configure the Git repository connection.
    6. -
  6. Enter a Credential Name, select the Git provider, and enter the Personal Access Token you obtained from the Git provider.
    7. -
  7. Click Save.
    8. -
-

Authorize GitHub with Choreo

-

Authorizing Choreo as a GitHub application grants Choreo the following permissions to perform the respective actions on your behalf within the repository:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
PermissionReadWriteDescription
IssuesYNRead component ID label to filter the pull requests
MetadataYNList repositories
ContentsYYList branches and create a branch to commit sample code
Pull RequestYYCreate a pull request if you start with a Choreo sample
WebhooksYYTrigger automatic deployment and configuration generation
-

Add Git submodules to a project

-

Choreo provides Git submodule support when you connect your GitHub repository to Choreo. This allows you to manage and include external repositories effectively within Choreo build pipelines. Key benefits of this capability include:

-
    -
  • Code sharing without duplication: Use submodules to maintain shared libraries across multiple projects, ensuring a single source of truth.
    • -
  • Efficient third-party library management: Manage third-party libraries as submodules to update them independently and track changes easily, avoiding direct code integration.
    • -
-

For example, when you work with the Micro Integrator (MI) runtime in Choreo, you can use Git submodules to reuse MI templates and sequences across components without duplication.

-
-

Tip

-

If you encounter an error stating that you cannot clone a submodule due to insufficient permissions, follow the instructions below to grant the necessary permissions:

-
    -
  • -

    For a personal account:

    -
      -
    1. Sign in to your personal GitHub account.
      2. -
    2. In the upper-right corner, click your profile picture, and then click Settings.
      3. -
    3. In the left navigation menu, go to the Integrations section and click Applications.
      4. -
    4. Under the Installed GitHub Apps tab, click Configure corresponding to choreo.dev.
      5. -
    5. Under Repository Access, grant access to the necessary repositories.
      6. -
    -
    • -
  • -

    For an organization account:

    -
      -
    1. Sign in to your organization's GitHub account.
      2. -
    2. In the upper-right corner, click your profile picture, and then click Settings.
      3. -
    3. In the left navigation menu, go to the Third-Party Access section and click GitHub Apps.
      4. -
    4. Click Configure corresponding to choreo.dev.
      5. -
    5. -

      Under Repository Access, grant access to the necessary repositories.

      -
      -

      Note

      -

      Choreo currently does not support accessing private repositories in other organizations.

      -
      -
      6. -
    -
    • -
-
-

Authorize Bitbucket with Choreo

-

Authorizing using a personal access token (PAT) from Bitbucket grants Choreo the following permissions to perform the respective actions on your behalf within the repository.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
PermissionReadWriteDescription
AccountYNGet user information and workspace details
RepositoriesYYList branches and create a branch to commit sample code
Pull RequestsYYCreate a pull request if you start with a Choreo sample
WebhooksYYTrigger automatic deployment and configuration generation
-

Authorize self-managed GitLab with Choreo

-

Authorizing using a personal access token (PAT) obtained from your GitLab self-managed server grants Choreo the following permissions to perform the respective actions on your behalf within the repository.

- - - - - - - - - - - - - -
PermissionDescription
APIGrants full read/write access to the API, covering all groups and projects, as well as read/write access to the repository.
- - - - - - -
-
- - -
- - - -
- - -
- - - -
-
-
- - - - - - - - - - - - - - - - - \ No newline at end of file diff --git a/en/site/develop-components/develop-integrations/develop-a-manual-task/index.html b/en/site/develop-components/develop-integrations/develop-a-manual-task/index.html deleted file mode 100644 index c4493ecdc..000000000 --- a/en/site/develop-components/develop-integrations/develop-a-manual-task/index.html +++ /dev/null @@ -1,3559 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - Develop a Manual Task - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- - - -
- - - - - - -
- - -
- -
- - - - - - - -
-
- - - -
-
-
- - - - -
-
-
- - - -
-
-
- - - -
-
-
- - - -
-
- - - - - - - - - - - - - - - - - - - - -

Develop a Manual Task

-

This guide walks you through the steps to develop, deploy, test, and observe a manual task using Choreo.

-

In this guide, you will:

-
    -
  • Develop a manual task to fetch the weather forecast for a specified location for the next 24 hours from the OpenWeatherMap API.
    • -
  • Process the weather data to a specific format.
    • -
  • Send the formatted data to a specified email address.
    • -
-

Prerequisites

-

Before you try out the steps in this guide, complete the following:

-
    -
  • -

    If you are signing in to the Choreo Console for the first time, create an organization as follows:

    -
      -
    1. Go to https://console.choreo.dev/, and sign in.
      2. -
    2. Enter a unique organization name. For example, Stark Industries.
      3. -
    3. Read and accept the privacy policy and terms of use.
      4. -
    4. Click Create. - This creates the organization and opens the Project Home page of the default project created for you.
      5. -
    -
    • -
  • -

    Fork the Choreo samples repository, which contains the sample integration for this guide.

    -
    -

    Repository file structure

    -

    To work with the sample repository, it is important to familiarize yourself with the repository file structure. The sample code for this guide is in the <sample-repository-dir>/weather-to-email-integration directory. To understand how the functionality is implemented, you must read the code comments. The following table describes what you will find in each file in the repository:

    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    File pathFile content
    Ballerina.tomlContains metadata about the project
    Dependencies.tomlLists the dependencies required for the project
    main.balContains the entry point of the project, including the main function
    types.balContains custom data types used in the project
    utils.balContains utility functions and helper functions used in the project
    -
    -
    • -
  • -

    Go to OpenWeatherMap and sign up to obtain an API key. For details on how to obtain an API key, see the OpenWeatherMap documentation.

    -
    • -
-

Step 1: Create a manual task component

-
    -
  1. Go to https://console.choreo.dev/ and sign in. This opens the project home page.
    2. -
  2. If you already have one or more components in your project, click + Create. Otherwise, proceed to the next step.
    3. -
  3. Click the Manual Task card.
    4. -
  4. -

    Enter a unique name and a description for the component. You can use the name and description given below:

    - - - - - - - - - - - - - - - - - -
    FieldValue
    Component NameWeatherToEmail
    DescriptionMy first manual task
    -
    5. -
  5. -

    Go to the GitHub tab.

    -
    6. -
  6. -

    To allow Choreo to connect to your GitHub account, click Authorize with GitHub. If you have not already connected your GitHub repository to Choreo, enter your GitHub credentials and select the repository you created in the prerequisites section to install the Choreo GitHub App.

    -

    Alternatively, you can paste the Choreo samples repository URL in the Provide Repository URL field to connect to it without requiring authorization from the Choreo Apps GitHub application. However, authorizing the repository with the Choreo GitHub App is necessary if you want to enable Auto Deploy for the component.

    -
    -

    Note

    -

    The Choreo GitHub App requires the following permissions:

    -
      -
    • Read and write access to code and pull requests.
      • -
    • Read access to issues and metadata.
      • -
    -

    You can revoke access if you do not want Choreo to have access to your GitHub account. However, write access is exclusively utilized for sending pull requests to a user repository. Choreo will not directly push any changes to a repository.

    -
    -
    7. -
  7. -

    Enter the following information:

    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    FieldDescription
    OrganizationYour GitHub account
    Repositorychoreo-samples
    Branchmain
    BuildpackBallerina
    Project Directoryweather-to-email-integration
    -
    -

    Tip

    -
      -
    • -

      Buildpack specifies the type of build to run depending on the implementation of the component. It converts the integration code into a Docker image that can run on Choreo cloud. If an integration is developed using WSO2 Integration Studio, select Micro Integrator as the buildpack. If an integration is developed using the Ballerina language, select Ballerina as the buildpack.

      -
      • -
    • -

      Project Directory specifies the location of the project to build the component.

      -
      • -
    -
    -
    8. -
  8. -

    Click Create. Choreo initializes the component with the sample implementation and opens the Overview page of the component.

    -
    9. -
-

Step 2: Build the manual task

-

To build the manual task, follow the steps given below:

-
    -
  1. In the left navigation menu, click Build.
    2. -
  2. In the Builds pane, click Build. This opens the Commits pane where you can see all the commits related to the component.
    3. -
  3. -

    Select the latest commit and click Build. This triggers the build process and displays the build progress in the Build Logs pane.

    -
    -

    Info

    -

    The build process can take a while to complete. When the build process is complete, the build will be listed in the Builds pane along with the build status.

    -
    -
    4. -
-

Here, you will see the build status as Success.

-

Step 3: Deploy the manual task

-

To deploy the manual task, follow the steps given below:

-
    -
  1. In the left navigation menu, click Deploy.
    2. -
  2. In the Set Up card, click Configure & Deploy.
    3. -
  3. -

    In the Configurations pane, specify values as follows for the configurable variables:

    -
    -

    Tip

    -

    The configurable variables populated here are defined in the sample Ballerina project used in this guide. To learn how to declare configurable variables in Ballerina, see the Ballerina documentation on declaring configurable variables. If configurable variables are detected in a connected Ballerina project, Choreo prompts for the respective values during component deployment.

    -
    - - - - - - - - - - - - - - - - - - - - - - - - - -
    FieldValue
    apiKeyThe API key you obtained in the prerequisites section
    latitudeLatitude of the location to get the weather forecast
    longitudeLongitude of the location to get the weather forecast
    emailThe email address to receive the formatted weather forecast information
    -
    -

    Note

    -

    If you use Ballerina as the buildpack and you want to set a configurable variable as a secret, click the lock icon corresponding to the configurable variable. This marks it as a secret and conceals the input value.

    -

    For example, if you consider the configurable variables in this guide and set the apiKey as a secret, its input value will be concealed as follows:

    -

    Configurable variable as a secret

    -

    If you want to update the input value at a later time, you can click Update Secret Content and specify a new value.

    -

    Update secret

    -
    -
    4. -
  4. -

    Click Deploy.

    -
    5. -
-

Step 4: Execute the manual task

-

To execute the manual task, follow the steps given below:

-
    -
  1. In the left navigation menu, click Execute.
    2. -
  2. -

    Click Run Now. This triggers the task.

    -
    -

    Inject dynamic values into your application as command-line arguments

    -

    If you want to inject dynamic values into your application as command-line arguments when you run a manual task, follow the steps given below:

    -
      -
    1. Click the drop-down icon next to Run Now and then click Run with Arguments.
      2. -
    2. In the Runtime Arguments pane that opens, enter the arguments you want to pass to your application.
      3. -
    3. Click Execute. This triggers the task with the specified arguments.
      4. -
    -

    The capability to run a manual task with arguments is supported for the following buildpacks:

    -
    -
    -
    -

    To explore a Dockerfile-based manual task with arguments, try out the Hello World Task sample. For instructions, see the readme.md file in the sample repository.

    -
    -

    Info

    -

    When you work on Docker projects, the Run with Arguments capability is not supported if the Dockerfile contains CMD. In such scenarios, you must use ENTRYPOINT to define your default commands.

    -
    -
    -
    -

    To explore a Go-based manual task with arguments, try out the Hello World Go Task sample. For instructions, see the readme.md file in the sample repository.

    -
    -
    -

    To explore a Java-based manual task with arguments, try out the Hello World Java Task sample. For instructions, see the readme.md file in the sample repository.

    -
    -

    Info

    -

    When you work on Java projects:

    -
      -
    • The Run with Arguments capability is not supported if Procfile is available in the project.
      • -
    • The Main class should be defined in the manifest file.
      • -
    • If Maven files such as mvn.cmd exist in the project without the .mvn directory, the build will fail. To ensure a successful build, you must either commit the .mvn directory along with any Maven files or not include any Maven files in the project if you choose not to commit the .mvn directory.
      • -
    -
    -
    -
    -

    To explore a NodeJS-based manual task with arguments, try out the Hello World NodeJS Task sample. For instructions, see the readme.md file in the sample repository.

    -
    -

    Info

    -

    When you work on NodeJS projects:

    -
      -
    • The Run with Arguments capability is not supported if Procfile is available in the project.
      • -
    • The project root must contain the package.json file with the main attribute defined.
      • -
    -
    -
    -
    -

    To explore a WSO2 MI-based manual task with arguments, try out the Weather to Logs Task sample. For instructions, see the readme.md file in the sample repository.

    -
    -

    Info

    -

    When you work on WSO2 MI projects and you want to deploy a WSO2 MI integration as a manual task in Choroeo, you must use the WSO2 MI automation mode. For details, see Running the Micro Integrator in Automation Mode.

    -
    -
    -
    -

    To explore a Ballerina manual task with arguments, try out the Weather to Email Task sample. For instructions, see the README.md file in the sample repository.

    -
    -

    Info

    -

    If you want to pass arguments to Ballerina main functions, you can use the Run with Arguments capability. For details on the arguments you can pass, see the Ballerina documentation. You can also override configurable values in the same manner. For more information, see Provide values to configurable variables.

    -
    -
    -
    -
    -
    -
    3. -
-

Step 5: Test the manual task

-

Once the task is triggered, an email with the subject [WSO2 Choreo Demo] Next 24H Weather Forecast is sent from choreo.demo@gmail.com to the email address specified as the email configurable variable value in Step 3.

-

If the manual task ran successfully, you should receive an email similar to the following to the email address you specified:

-

Received email

-

Step 6: Observe the manual task

-

The observability view in Choreo displays graphs that depict details such as throughput, latency, diagnostic data, and logs to identify and troubleshoot anomalies in components you deploy.

-

To visualize and monitor the performance of the manual task you deployed, click Observability in the left navigation menu. You can observe the following:

-
    -
  • The throughput and latencies of requests served over a given period.
    • -
  • The logs that are generated over a given period.
    • -
  • The flame graph (Diagnostics View) that is generated over a given period.
    • -
  • The low-code diagram.
    • -
-

To learn more about the observability details you can view via Choreo observability, see Observability Overview.

-

Step 7: Monitor executions

-

To track and monitor executions associated with the deployed scheduled task, go to the left navigation menu and click Execute.

-
-

Tip

-

The Execute view is applicable to both scheduled and manual tasks.

-
-

You can view the following information:

-
    -
  • -

    The total number of executions within the past 30 days.

    -

    Total Execution

    -
    • -
  • -

    The currently active executions and those that are already complete.

    -

    Here, you can view information such as the execution ID, the revision of the execution, and the time it was triggered.

    -

    Execution History

    -
    • -
  • -

    Detailed execution logs for a specific execution.

    -

    You can click on an execution to view detailed logs related to it.

    -
    -

    Info

    -

    It may take a few minutes for the logs to appear. You may need to manually refresh to view the latest logs.

    -
    -

    Execution History

    -
    • -
- - - - - - -
-
- - -
- - - -
- - -
- - - -
-
-
- - - - - - - - - - - - - - - - - \ No newline at end of file diff --git a/en/site/develop-components/develop-integrations/develop-a-scheduled-task/index.html b/en/site/develop-components/develop-integrations/develop-a-scheduled-task/index.html deleted file mode 100644 index de35bbb20..000000000 --- a/en/site/develop-components/develop-integrations/develop-a-scheduled-task/index.html +++ /dev/null @@ -1,3514 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - Develop a Scheduled Task - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- - - -
- - - - - - -
- - -
- -
- - - - - - - -
-
- - - -
-
-
- - - - -
-
-
- - - -
-
-
- - - -
-
-
- - - -
-
- - - - - - - - - - - - - - - - - - - - -

Develop a Scheduled Task

-

Choreo is a versatile integration platform that allows you to create various types of integrations depending on your requirement.

-

If you have a requirement to automatically run a specific integration at regular intervals, you can use Choreo to develop a scheduled task. This type of integration can automate the synchronization of data between different systems at specified intervals, reducing errors and improving productivity by eliminating the need for manual intervention.

-

This guide walks you through the steps to develop, deploy, test, and observe a scheduled task using Choreo.

-

In this guide, you will:

-
    -
  • Develop a scheduled task to fetch the weather forecast for a specified location for the next 24 hours from the OpenWeatherMap API.
    • -
  • Process the weather data to a specific format.
    • -
  • Send the formatted data to a specified email address at a specific time every day.
    • -
-

Prerequisites

-

Before you try out the steps in this guide, complete the following:

-
    -
  • -

    If you are signing in to the Choreo Console for the first time, create an organization as follows:

    -
      -
    1. Go to https://console.choreo.dev/, and sign in using your preferred method.
      2. -
    2. Enter a unique organization name. For example, Stark Industries.
      3. -
    3. Read and accept the privacy policy and terms of use.
      4. -
    4. Click Create. - This creates the organization and opens the Project Home page of the default project created for you.
      5. -
    -
    • -
  • -

    Fork the Choreo samples repository, which contains the sample integration for this guide.

    -
    -

    Repository file structure

    -

    To work with the sample repository, it is important to familiarize yourself with the repository file structure. The sample code for this guide is in the <sample-repository-dir>/weather-to-email-scheduled-task directory. To understand how the functionality is implemented, you must read the code comments. The following table describes what you will find in each file in the repository:

    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    File pathFile content
    Ballerina.tomlContains metadata about the project
    Dependencies.tomlLists the dependencies required for the project
    main.balContains the entry point of the project, including the main function
    types.balContains custom data types used in the project
    utils.balContains utility functions and helper functions used in the project
    -
    -
    • -
  • -

    Go to OpenWeatherMap and sign up to obtain an API key. For details on how to obtain an API key, see the OpenWeatherMap documentation.

    -
    • -
-

Step 1: Create a scheduled task component

-
    -
  1. Go to https://console.choreo.dev/ and sign in. This opens the project home page.
    2. -
  2. If you already have one or more components in your project, click + Create. Otherwise, proceed to the next step.
    3. -
  3. Click the Scheduled Task card.
    4. -
  4. -

    Enter a unique name and a description for the component. You can use the name and description given below:

    - - - - - - - - - - - - - - - - - -
    FieldValue
    Component NameWeatherToEmail
    DescriptionMy first scheduled task
    -
    5. -
  5. -

    Go to the GitHub tab.

    -
    6. -
  6. -

    To allow Choreo to connect to your GitHub account, click Authorize with GitHub. If you have not already connected your GitHub repository to Choreo, enter your GitHub credentials and select the repository you created in the prerequisites section to install the Choreo GitHub App.

    -

    Alternatively, you can paste the Choreo samples repository URL in the Provide Repository URL field to connect to it without requiring authorization from the Choreo Apps GitHub application. However, authorizing the repository with the Choreo GitHub App is necessary if you want to enable Auto Deploy for the component.

    -
    -

    Note

    -

    The Choreo GitHub App requires the following permissions:

    -
      -
    • Read and write access to code and pull requests.
      • -
    • Read access to issues and metadata.
      • -
    -

    You can revoke access if you do not want Choreo to have access to your GitHub account. However, write access is exclusively utilized for sending pull requests to a user repository. Choreo will not directly push any changes to a repository.

    -
    -
    7. -
  7. -

    Enter the following information:

    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    FieldDescription
    OrganizationYour GitHub account
    Repositorychoreo-samples
    Branchmain
    BuildpackBallerina
    Project Directoryweather-to-email-scheduled-task
    -
    -

    Tip

      -
    • Buildpack specifies the type of build to run depending on the implementation of the component. It converts the integration code into a Docker image that can run on Choreo cloud. If an integration is developed using WSO2 Integration Studio, select Micro Integrator as the buildpack. If an integration is developed using the Ballerina language, select Ballerina as the buildpack.
      • -
    -

    -
      -
    • Project Directory specifies the location of the project to build the component.
      • -
    -
    -
    8. -
  8. -

    Click Create. Choreo initializes the component with the sample implementation and opens the Overview page of the component.

    -
    9. -
-

Now you can proceed to build and deploy the scheduled task.

-

Step 2: Build the scheduled task

-

To build the scheduled task, follow the steps given below:

-
    -
  1. In the left navigation menu, click Build.
    2. -
  2. In the Builds pane, click Build. This opens the Commits pane where you can see all the commits related to the component.
    3. -
  3. -

    Select the latest commit and click Build. This triggers the build process and displays the build progress in the Build Logs pane.

    -
    -

    Info

    -

    The build process can take a while to complete. When the build process is complete, the build will be listed in the Builds pane along with the build status.

    -
    -
    4. -
-

Here, you will see the build status as Success.

-

Step 3: Deploy the scheduled task

-

To deploy the scheduled task, follow the steps given below:

-
    -
  1. In the left navigation menu, click Deploy.
    2. -
  2. In the Set Up card, click Configure & Deploy.
    3. -
  3. -

    In the Configurations pane, specify values as follows for the configurable variables:

    -
    -

    Tip

    -

    The configurable variables populated here are defined in the sample Ballerina project used in this guide. To learn how to declare configurable variables in Ballerina, see the Ballerina documentation on declaring configurable variables. If configurable variables are detected in a connected Ballerina project, Choreo prompts for the respective values during component deployment.

    -
    - - - - - - - - - - - - - - - - - - - - - - - - - -
    FieldValue
    apiKeyThe API key you obtained in the prerequisites section
    latitudeLatitude of the location to get the weather forecast
    longitudeLongitude of the location to get the weather forecast
    emailThe email address to receive the formatted weather forecast information
    -
    -

    Note

    -

    If you use Ballerina as the buildpack and you want to set a configurable variable as a secret, click the lock icon corresponding to the configurable variable. This marks it as a secret and conceals the input value.

    -

    For example, if you consider the configurable variables in this guide and set the apiKey as a secret, its input value will be concealed as follows:

    -

    Configurable variable as a secret

    -

    If you want to update the input value at a later time, you can click Update Secret Content and specify a new value.

    -

    Update secret

    -
    -
    4. -
  4. -

    Click Next.

    -
    5. -
  5. -

    In this step, you must define a schedule to run the task. In this guide, you set the schedule to receive the weather information daily at 8.00 AM UTC. Enter values as follows to configure the schedule:

    - - - - - - - - - - - - - - - - - - - - - - - - - -
    FieldValue
    Select Time ZoneSelect a time zone to schedule the task
    Select RangeDay
    Every1
    At08:00
    -
    -

    Tip

    -

    When you develop a scheduled task, you can define a schedule depending on your requirement. If you want to test and verify the immediately, you can schedule the deployment to run in just a few minutes after you create it. However, to avoid unnecessary expenses, make sure you reschedule or stop the deployment once you test and verify.

    -
    -
    6. -
  6. -

    Click Deploy. This deploys the scheduled task to the development environment and indicates the Scheduled Status as Active in the Development card.

    -
    7. -
-

You can test the scheduled task when it runs at the configured time.

-

Step 4: Test the scheduled task

-

When the scheduled task runs at the configured time, an email with the subject [WSO2 Choreo Demo] Next 24H Weather Forecast is sent from choreo.demo@gmail.com to the email address specified as the email configurable variable value in Step 3.

-

If the scheduled task ran successfully, you should receive an email similar to the following to the email address you specified:

-

Received email

-

Step 5: Observe the scheduled task

-

The observability view in Choreo displays graphs that depict details such as throughput, latency, diagnostic data, and logs to identify and troubleshoot anomalies in components you deploy.

-

To visualize and monitor the performance of the scheduled task you deployed, click Observability in the left navigation menu. You can observe the following:

-
    -
  • The throughput and latencies of requests served over a given period.
    • -
  • The logs that are generated over a given period.
    • -
  • The flame graph (Diagnostics View) that is generated over a given period.
    • -
  • The low-code diagram.
    • -
-

To learn more about the observability details you can view via Choreo observability, see Observability Overview.

-

Step 6: Monitor executions

-

To track and monitor executions associated with the deployed scheduled task, go to the left navigation menu and click Execute.

-
-

Tip

-

The Execute view is applicable to both scheduled and manual tasks.

-
-

You can view the following information:

-
    -
  • -

    The total number of executions within the past 30 days.

    -

    Total Execution

    -
    • -
  • -

    The currently active executions and those that are already complete.

    -

    Here, you can view information such as the execution ID, the revision of the execution, and the time it was triggered.

    -

    Execution History

    -
    • -
  • -

    Detailed execution logs for a specific execution.

    -

    You can click on an execution to view detailed logs related to it.

    -
    -

    Info

    -

    It may take a few minutes for the logs to appear. You may need to manually refresh to view the latest logs.

    -
    -

    Execution History

    -
    • -
- - - - - - -
-
- - -
- - - -
- - -
- - - -
-
-
- - - - - - - - - - - - - - - - - \ No newline at end of file diff --git a/en/site/develop-components/develop-integrations/develop-an-event-handler/index.html b/en/site/develop-components/develop-integrations/develop-an-event-handler/index.html deleted file mode 100644 index a546fbd46..000000000 --- a/en/site/develop-components/develop-integrations/develop-an-event-handler/index.html +++ /dev/null @@ -1,3352 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - Develop an Event Handler - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- - - -
- - - - - - -
- - -
- -
- - - - - - - -
-
- - - -
-
-
- - - - -
-
-
- - - -
-
-
- - - -
-
-
- - - -
-
- - - - - - - - - - - - - - - - - - - - -

Develop an Event Handler

-

An Event Handler executes predefined actions in response to specific events. Choreo simplifies the process of creating and deploying such integrations.

-

This guide walks you through the steps to create and deploy an Event Handler using WSO2 MI and Choreo.

-

In this guide, you will build a simple event handler that monitors RabbitMQ for new messages and displays them once they become available.

-

Prerequisites

-

Before you try out the steps in this guide, complete the following:

-
    -
  • -

    If you are signing in to the Choreo Console for the first time, create an organization as follows:

    -
      -
    1. Go to https://console.choreo.dev/, and sign in using your preferred method.
      2. -
    2. Enter a unique organization name. For example, Stark Industries.
      3. -
    3. Read and accept the privacy policy and terms of use.
      4. -
    4. Click Create. - This creates the organization and opens the Project Home page of the default project created for you.
      5. -
    -
    • -
  • -

    Use an existing RabbitMQ instance or start a new RabbitMQ instance on a server that can be accessed via the internet. Obtain the username, hostname, password, and vhost from the RabbitMQ instance to use later as environment variables.

    -
    • -
  • -

    Fork the Choreo samples repository, which contains the sample integration for this guide.

    -
    • -
-

Step 1: Create an event handler component

-
    -
  1. Go to https://console.choreo.dev/ and sign in. This opens the project home page.
    2. -
  2. If you already have one or more components in your project, click + Create. Otherwise, proceed to the next step.
    3. -
  3. Click the Event Handler card.
    4. -
  4. -

    Enter a unique name and a description for the component. You can use the name and description given below:

    - - - - - - - - - - - - - - - - - -
    FieldValue
    Component NameSalesOrderListener
    DescriptionRabbitMQ integration
    -
    5. -
  5. -

    Go to the GitHub tab.

    -
    6. -
  6. -

    To allow Choreo to connect to your GitHub account, click Authorize with GitHub. If you have not already connected your GitHub repository to Choreo, enter your GitHub credentials and select the repository you created in the prerequisites section to install the Choreo GitHub App.

    -

    Alternatively, you can paste the Choreo samples repository URL in the Provide Repository URL field to connect to it without requiring authorization from the Choreo Apps GitHub application. However, authorizing the repository with the Choreo GitHub App is necessary if you want to enable Auto Deploy for the component.

    -
    -

    Note

    -

    The Choreo GitHub App requires the following permissions:

    -
      -
    • Read and write access to code and pull requests.
      • -
    • Read access to issues and metadata.
      • -
    -

    You can revoke access if you do not want Choreo to have access to your GitHub account. However, write access is exclusively utilized for sending pull requests to a user repository. Choreo will not directly push any changes to a repository.

    -
    -
    7. -
  7. -

    Enter the following information:

    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    FieldDescription
    OrganizationYour GitHub account
    Repositorychoreo-samples
    Branchmain
    BuildpackWSO2 MI because you are creating the REST API from a WSO2 Integration Studio project
    Project Directorymi-rabbitmq-listener
    -
    -

    Tip

      -
    • Buildpack specifies the type of build to run depending on the implementation of the component. It converts the integration code into a Docker image that can run on Choreo cloud. If an integration is developed using WSO2 Integration Studio, select Micro Integrator as the buildpack. If an integration is developed using the Ballerina language, select Ballerina as the buildpack.
      • -
    -

    -
      -
    • Project Directory specifies the location of the project to build the component.
      • -
    -
    -
    8. -
  8. -

    Click Create.

    -
    9. -
-

Step 2: Deploy the integration

-

To deploy the integration, follow the steps given below:

-
    -
  1. In the left navigation menu, click Deploy.
    2. -
  2. In the Build Area card, click Configure & Deploy.
    3. -
  3. -

    In the Configurations pane, click + Add corresponding to Environment Variables and add the following environment variables:

    -
    -

    Tip

    Use the values from your RabbitMQ instance as per the Prerequisites section, for the environment variables.

    -

    -
    - - - - - - - - - - - - - - - - - - - - - - - - - -
    NameValue
    HOSTNAMEHostname of your RabbitMQ server
    VHOSTVirtual hostname of your RabbitMQ server
    USERNAMEUsername for connecting to RabbitMQ
    PASSWORDPassword associated with the RabbitMQ username
    -
    4. -
  4. -

    Click Deploy. This deploys the event handler to the development environment and indicates the Deployment Status as Active in the Development card.

    -
    5. -
-

Step 3: Test the integration

-

To test the integration, follow the steps given below:

-
    -
  1. Send a sales order message to the SalesOrderQueue on the RabbitMQ server.
      -
    • You can send a sample sales order message similar to the following: - 
      {
-    "order_id": "12345",
-    "customer_name": "John Doe",
-    "product": "Widget",
-    "quantity": 10,
-    "total_amount": 100.00
-}
-
      • -
    -
    2. -
  2. Observe the logs:
      -
    • In the left navigation menu, click Logs and then click Runtime Logs. You will see the order message in the logs.
      • -
    -
    3. -
-

Now you have gained hands-on experience in creating, configuring, and deploying an event handler.

- - - - - - -
-
- - -
- - - -
- - -
- - - -
-
-
- - - - - - - - - - - - - - - - - \ No newline at end of file diff --git a/en/site/develop-components/develop-integrations/develop-an-integration-with-integration-studio/index.html b/en/site/develop-components/develop-integrations/develop-an-integration-with-integration-studio/index.html deleted file mode 100644 index 94e2f044d..000000000 --- a/en/site/develop-components/develop-integrations/develop-an-integration-with-integration-studio/index.html +++ /dev/null @@ -1,3366 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - Develop an Integration with Integration Studio - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- - - -
- - - - - - -
- - -
- -
- - - - - - - -
-
- - - -
-
-
- - - - -
-
-
- - - -
-
-
- - - -
-
-
- - - -
-
- - - - - - - - - - - - - - - - - - - - -

Develop an Integration with Integration Studio

-

The seamless integration of APIs, microservices, applications, and data across different languages and formats requires the ability to expose integrations as APIs. Choreo simplifies building, deploying, and managing integration components, making it easy for you to quickly expose integrations as APIs.

-
-

Note

-
    -
  • To develop integrations that you need to use in Manual Task and Schedule Task components in Choreo, you need to use the automation mode in the WSO2 Micro Integrator. See Running MI in Automation Mode.
    • -
  • To develop integrations for any other component types (Service, webhook, event-handler, etc) you need to use the server mode.
    • -
-
-

This guide walks you through the steps to expose an integration you created in WSO2 Integration Studio as an API in Choreo.

-

In this guide, you will:

-
    -
  • Create a component to expose the sample integration in the Choreo samples repository as an API.
    • -
  • Deploy, test, and observe the integration component.
    • -
  • Publish the integration component as an API to the Choreo Developer Portal.
    • -
-

Prerequisites

-

Before you try out the steps in this guide, complete the following:

-
    -
  • -

    If you are signing in to the Choreo Console for the first time, create an organization as follows:

    -
      -
    1. Go to https://console.choreo.dev/, and sign in using your preferred method.
      2. -
    2. Enter a unique organization name. For example, Stark Industries.
      3. -
    3. Read and accept the privacy policy and terms of use.
      4. -
    4. Click Create. - This creates the organization and opens the Project Home page of the default project created for you.
      5. -
    -
    • -
  • -

    Fork the Choreo samples repository, which contains the sample integration for this guide.

    -
    • -
-

Step 1: Create the integration component

-
    -
  1. Go to https://console.choreo.dev/ and sign in. This opens the project home page.
    2. -
  2. If you already have one or more components in your project, click + Create. Otherwise, proceed to the next step.
    3. -
  3. Click the Service card.
    4. -
  4. -

    Enter a unique name and a description for the component. You can enter the name and description given below:

    - - - - - - - - - - - - - - - - - -
    FieldValue
    Component NameHello World
    DescriptionHello World REST API
    -
    5. -
  5. -

    Go to the GitHub tab.

    -
    6. -
  6. -

    To allow Choreo to connect to your GitHub account, click Authorize with GitHub. If you have not already connected your GitHub repository to Choreo, enter your GitHub credentials and select the repository you created in the prerequisites section to install the Choreo GitHub App.

    -

    Alternatively, you can paste the Choreo samples repository URL in the Provide Repository URL field to connect to it without requiring authorization from the Choreo Apps GitHub application. However, authorizing the repository with the Choreo GitHub App is necessary if you want to enable Auto Deploy for the component.

    -
    -

    Note

    -

    The Choreo GitHub App requires the following permissions:

    -
      -
    • Read and write access to code and pull requests.
      • -
    • Read access to issues and metadata.
      • -
    -

    You can revoke access if you do not want Choreo to have access to your GitHub account. However, write access is exclusively utilized for sending pull requests to a user repository. Choreo will not directly push any changes to a repository.

    -
    -
    7. -
  7. -

    Enter the following information:

    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    FieldDescription
    OrganizationYour GitHub account
    Repositorychoreo-samples
    Branchmain
    BuildpackWSO2 MI because you are creating the REST API from a WSO2 Integration Studio project
    Project Directoryhello-world-mi
    -
    8. -
  8. -

    Click Create. Choreo initializes the component with the sample integration.

    -
    9. -
-

Step 2: Deploy the integration component

-

To deploy the integration component to the development environment, follow the steps given below:

-
    -
  1. In the Choreo Console left navigation menu, click Deploy.
    2. -
  2. In the Build Area card, click Configure & Deploy.
    3. -
  3. In the Configurations pane, click Next. This displays details of the endpoint ready to be deployed.
    4. -
  4. -

    Click Deploy. This deploys the integration component to the development environment. -The Development card indicates the Deployment Status as Active when the integration is successfully deployed.

    -
    -

    Tip

    -

    Choreo uses endpoints to expose Service component to the network. You can read more about configuring endpoints in Configure Endoints.

    -
    -
    -

    Tip

    -

    Automatic deployment is enabled for the component by default. Therefore, you are required to perform only the first deployment manually.

    -
    -
    5. -
-

Now you can test the integration.

-

Step 3: Test the integration

-

To test the integration using the OpenAPI Console. Follow the steps given below:

-
    -
  1. In the Choreo Console left navigation menu, click Test and then click Console.
    2. -
  2. In the OpenAPI Console that opens, select Development from the environment drop-down list.
    3. -
  3. Click to expand the GET /integration operation.
    4. -
  4. Click Try it out and then click Execute. This sends a request to your deployed integration.
    5. -
  5. -

    Go to the Response body section and observe the response returned by the integration. If the integration works as expected, you should see a response similar to the following:

    -

    {"Hello" : "Integration"}

    -
    6. -
-

Step 4: Observe the integration

-

The observability view in Choreo displays graphs that depict details such as throughput, latency, diagnostic data, and logs to identify and troubleshoot anomalies in components you deploy.

-

To visualize and monitor the performance of the integration component you deployed, click Observability in the left navigation menu. You can observe the following:

-
    -
  • The throughput and latencies of requests served over a given period.
    • -
  • The logs that are generated over a given period.
    • -
  • The flame graph (Diagnostics View) that is generated over a given period.
    • -
-

To learn more about the observability details you can view via Choreo observability, see Observability Overview.

-

Step 5: Publish the integration component

-

To publish the integration component, follow the steps given below:

-
    -
  1. In the Choreo Console left navigation menu, click Manage and then click Lifecycle. This opens the Lifecycle Management pane, where you can see the different lifecycle stages that an API can be in. You can see that the current lifecycle stage is Created.
    2. -
  2. In the Lifecycle Management pane, click Publish. This changes the API lifecycle stage to Published and exposes the integration as an API in the Choreo Developer Portal.
    3. -
-

To open the published API in the Developer Portal via the Lifecycle Management pane, click Go to Devportal. In the Choreo Developer Portal, you can view the published API, manage subscriptions for it, and generate access tokens for testing purposes.

-

Now, you have gained hands-on experience in exposing an integration designed using WSO2 Integration Studio as a REST API in Choreo.

- - - - - - -
-
- - -
- - - -
- - -
- - - -
-
-
- - - - - - - - - - - - - - - - - \ No newline at end of file diff --git a/en/site/develop-components/develop-services/develop-a-ballerina-graphql-api/index.html b/en/site/develop-components/develop-services/develop-a-ballerina-graphql-api/index.html deleted file mode 100644 index 973aa5be2..000000000 --- a/en/site/develop-components/develop-services/develop-a-ballerina-graphql-api/index.html +++ /dev/null @@ -1,15 +0,0 @@ - - - - - - Redirecting... - - - - - - -Redirecting... - - diff --git a/en/site/develop-components/develop-services/develop-a-ballerina-rest-api/index.html b/en/site/develop-components/develop-services/develop-a-ballerina-rest-api/index.html deleted file mode 100644 index 04ce966b6..000000000 --- a/en/site/develop-components/develop-services/develop-a-ballerina-rest-api/index.html +++ /dev/null @@ -1,15 +0,0 @@ - - - - - - Redirecting... - - - - - - -Redirecting... - - diff --git a/en/site/develop-components/develop-services/develop-a-ballerina-service/index.html b/en/site/develop-components/develop-services/develop-a-ballerina-service/index.html deleted file mode 100644 index f5dadd66b..000000000 --- a/en/site/develop-components/develop-services/develop-a-ballerina-service/index.html +++ /dev/null @@ -1,3436 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - Develop a Ballerina Service - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- - - -
- - - - - - -
- - -
- -
- - - - - - - -
-
- - - -
-
-
- - - - -
-
-
- - - -
-
-
- - - -
-
-
- - - -
-
- - - - - - - - - - - - - - - - - - - - -

Develop a Ballerina Service

-

Choreo allows you to develop and deploy applications using your preferred programming language. This guide demonstrates how to deploy a service component that exposes a REST API using the Ballerina language. No prior knowledge of the Ballerina language is required to follow this guide.

-

A REST API is a web service adhering to Representational State Transfer (REST) principles, using HTTP methods to access and manage resources. This guide walks you through building a Ballerina service component, deploying it on Choreo, and using it with an HTTP client application.

-

In this guide, you will:

-
    -
  • -

    Build a simple greeting service using a sample service implementation. The sample implementation will have a single resource named greet that accepts a single query parameter as input.

    -
      -
    • -

      Request:

      -

      $ curl GET http://localhost:9090/greeter/greet?name=Ballerina

      -
      • -
    • -

      Response:

      -

      $ hello Ballerina!

      -
      • -
    -
    • -
  • -

    Deploy the service in Choreo. The service will run on port 9090.

    -
    • -
  • Test the service.
    • -
-

Prerequisites

-

Before you try out this guide, complete the following:

-
    -
  • -

    If you are signing in to the Choreo Console for the first time, create an organization as follows:

    -
      -
    1. Go to https://console.choreo.dev/, and sign in using your preferred method.
      2. -
    2. Enter a unique organization name. For example, Stark Industries.
      3. -
    3. Read and accept the privacy policy and terms of use.
      4. -
    4. Click Create.
      5. -
    -

    This creates the organization and opens the Project Home page of the default project created for you.

    -
    • -
  • -

    Fork the Choreo samples repository, which contains the sample greetings service implementation in Ballerina.

    -
    • -
-

Learn the repository file structure

-

It is important to understand the purpose of the key files in the sample service. The following table provides a brief overview of each file in the greeter service:

-
-

Note

-

The specified file paths are relative to <sample-repository-dir>/greeting-service.

-
- - - - - - - - - - - - - - - - - - - - - -
FilepathDescription
service.balThe greetings service code written in the Ballerina language.
tests/service_test.balTest files related to the service.bal file.
Ballerina.tomlThe Ballerina configuration file.
-

Let's get started!

-

Step 1: Create a service component

-

To create a Ballerina service component, follow these steps:

-
    -
  1. Go to https://console.choreo.dev/ and sign in. This opens the project home page.
    2. -
  2. If you already have one or more components in your project, click + Create. Otherwise, proceed to the next step.
    3. -
  3. Click the Service card.
    4. -
  4. -

    Enter a display name, a unique name, and a description for the service component. You can enter the values given below:

    -
    -

    Info

    -

    In the Component Name field, you must specify a name to uniquely identify the component in various contexts. The value is editable only at the time you create the component. You cannot change the name after you create the component.

    -
    - - - - - - - - - - - - - - - - - - - - - -
    FieldValue
    Component Display NameBallerina Greetings
    Component Nameballerina-greetings
    DescriptionSend greetings
    -
    5. -
  5. -

    Go to the GitHub tab.

    -
    6. -
  6. -

    To allow Choreo to connect to your GitHub account, click Authorize with GitHub. If you have not already connected your GitHub repository to Choreo, enter your GitHub credentials and select the repository you created in the prerequisites section to install the Choreo GitHub App.

    -

    Alternatively, you can paste the Choreo samples repository URL in the Provide Repository URL field to connect to it without requiring authorization from the Choreo Apps GitHub application. However, authorizing the repository with the Choreo GitHub App is necessary if you want to enable Auto Deploy for the component.

    -
    -

    Note

    -

    The Choreo GitHub App requires the following permissions:

    -
      -
    • Read and write access to code and pull requests.
      • -
    • Read access to issues and metadata.
      • -
    -

    You can revoke access if you do not want Choreo to have access to your GitHub account. However, write access is exclusively utilized for sending pull requests to a user repository. Choreo will not directly push any changes to a repository.

    -
    -
    7. -
  7. -

    Under Connect Your Repository, enter the following information:

    - - - - - - - - - - - - - - - - - - - - - -
    FieldValue
    OrganizationYour GitHub account
    Repositorychoreo-samples
    Branchmain
    -
    8. -
  8. -

    Select Ballerina as the buildpack.

    -
    9. -
  9. In the Ballerina Project Directory, specify /greeting-service.
    10. -
  10. Click Create. This creates the component and takes you to the Overview page of the component.
    11. -
-

You have successfully created a service that exposes a REST API written in the Ballerina language. Next, let's build and deploy the service.

-

Step 2: Build and deploy

-

Now that you have connected the source repository and configured the endpoint details, it's time to build and deploy the service.

-
-

Note

-

If you are rebuilding the Ballerina service component after changing the Ballerina version, ensure that before building the code, the version of the Ballerina distribution mentioned in the Ballerina.toml file matches the distribution version specified in the Dependencies.toml file.

-
-

Step 2.1: Build

-

To build the service, follow these steps:

-
    -
  1. In the left navigation menu, click Build.
    2. -
  2. -

    On the Build page, click Build Latest.

    -
    -

    Note

    -

    Building the service component may take a while. You can track the progress via the logs in the Build Details pane. Once the build process is complete, the build status changes to Success.

    -
    -
    3. -
-

Step 2.2: Deploy

-

To deploy the service, follow these steps:

-
    -
  1. In the left navigation menu, click Deploy.
    2. -
  2. On the Set Up card, click Configure & Deploy.
    3. -
  3. In the Configurations pane that opens, click Next to skip the configuration.
    4. -
  4. -

    Review the Endpoint Details and click Deploy.

    -
    -

    Note

    -

    Deploying the service component may take a while. Once deployed, the Development environment card indicates the Deployment Status as Active.

    -
    -

    To build and deploy the service, follow the steps below:

    -
    5. -
-

Once you have successfully deployed your service, you can test, manage, and observe it like any other component type in Choreo.

-

For detailed instructions, see the following sections:

- -

Manage the deployment

-

If you want to view Kubernetes-level insights to perform a more detailed diagnosis of this Ballerina REST API, see Choreo's DevOps capabilities.

- - - - - - -
-
- - -
- - - -
- - -
- - - -
-
-
- - - - - - - - - - - - - - - - - \ No newline at end of file diff --git a/en/site/develop-components/develop-services/develop-a-go-rest-api/index.html b/en/site/develop-components/develop-services/develop-a-go-rest-api/index.html deleted file mode 100644 index 135917fcf..000000000 --- a/en/site/develop-components/develop-services/develop-a-go-rest-api/index.html +++ /dev/null @@ -1,15 +0,0 @@ - - - - - - Redirecting... - - - - - - -Redirecting... - - diff --git a/en/site/develop-components/develop-services/develop-a-grpc-service/index.html b/en/site/develop-components/develop-services/develop-a-grpc-service/index.html deleted file mode 100644 index 2ee3b646c..000000000 --- a/en/site/develop-components/develop-services/develop-a-grpc-service/index.html +++ /dev/null @@ -1,15 +0,0 @@ - - - - - - Redirecting... - - - - - - -Redirecting... - - diff --git a/en/site/develop-components/develop-services/develop-a-rest-api/index.html b/en/site/develop-components/develop-services/develop-a-rest-api/index.html deleted file mode 100644 index d832de08e..000000000 --- a/en/site/develop-components/develop-services/develop-a-rest-api/index.html +++ /dev/null @@ -1,15 +0,0 @@ - - - - - - Redirecting... - - - - - - -Redirecting... - - diff --git a/en/site/develop-components/develop-services/develop-a-service-with-docker/index.html b/en/site/develop-components/develop-services/develop-a-service-with-docker/index.html deleted file mode 100644 index 94feeee3b..000000000 --- a/en/site/develop-components/develop-services/develop-a-service-with-docker/index.html +++ /dev/null @@ -1,3471 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - Develop a service with Docker - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- - - -
- - - - - - -
- - -
- -
- - - - - - - -
-
- - - -
-
-
- - - - -
-
-
- - - -
-
-
- - - -
-
-
- - - -
-
- - - - - - - - - - - - - - - - - - - - -

Develop a Service with Docker

-

Choreo is a platform that allows you to create and deploy applications in any language.

-

In this guide, you will:

-
    -
  • create a containerized service component using a sample service implementation. The sample implementation will have a single resource named greet that accepts a single query parameter as input.
    • -
  • Deploy it in Choreo using a Dockerfile. The service will run on port 9090.
    • -
  • Test the service.
    • -
-

If you want to create a service component that exposes a Ballerina service, see Develop a Ballerina Service .

-

Prerequisites

-

Before you try out this guide, complete the following:

-
    -
  • -

    If you are signing in to the Choreo Console for the first time, create an organization as follows:

    -
      -
    1. Go to https://console.choreo.dev/, and sign in using your preferred method.
      2. -
    2. Enter a unique organization name. For example, Stark Industries.
      3. -
    3. Read and accept the privacy policy and terms of use.
      4. -
    4. Click Create.
      5. -
    -

    This creates the organization and opens the Project Home page of the default project created for you.

    -
    • -
  • -

    Fork the Choreo samples repository, which contains the sample greetings service implementation with the Dockerfile.

    -
    • -
-

Learn the repository file structure

-

It is important to understand the purpose of the key files in the sample service. The following table provides a brief overview of each file in the greeter service:

-
-

Note

-

The specified file paths are relative to <sample-repository-dir>/greeting-service-go

-
- - - - - - - - - - - - - - - - - - - - - - - - - -
FilepathDescription
main.goThe Go-based greeter service code.
DockerfileThe Dockerfile to build the container image of the application.
.choreo/endpoints.yamlChoreo-specific configuration that provides information about how Choreo exposes the service.
openapi.yamlThe OpenAPI contract of the greeter service. This is required to publish the service as a managed API. This openapi.yaml file is referenced by the .choreo/endpoints.yaml file.
-

Let's get started!

-

Configure the service port with endpoints

-

In Choreo, you can expose your services via endpoints.

-

You are going to run the greeter service on port 9090. To securely expose the service through Choreo, you must provide the port and other required information to Choreo. For detailed information on each attribute of an endpoint, see Configure Endpoints.

-

To configure the endpoint details of a containerized component, Choreo looks for an endpoints.yaml file inside the .choreo directory. Be sure to place the .choreo directory at the root of the Docker build context path.

-

In the greeter sample, the endpoints.yaml file is in the greeting-service-go/.choreo/ directory.

-

Step 1: Create a service component from a Dockerfile

-

To create a containerized service component, follow these steps:

-
    -
  1. Go to https://console.choreo.dev/ and sign in. This opens the project home page.
    2. -
  2. If you already have one or more components in your project, click + Create. Otherwise, proceed to the next step.
    3. -
  3. Click the Service card.
    4. -
  4. -

    Enter a display name, a unique name, and a description for the service component. You can enter the values given below:

    -
    -

    Info

    -

    In the Component Name field, you must specify a name to uniquely identify the component in various contexts. The value is editable only at the time you create the component. You cannot change the name after you create the component.

    -
    - - - - - - - - - - - - - - - - - - - - - -
    FieldValue
    Component Display NameGreetings
    Component Namegreetings
    DescriptionSend greetings
    -
    5. -
  5. -

    Go to the GitHub tab.

    -
    6. -
  6. -

    To allow Choreo to connect to your GitHub account, click Authorize with GitHub. If you have not already connected your GitHub repository to Choreo, enter your GitHub credentials and select the repository you created in the prerequisites section to install the Choreo GitHub App.

    -

    Alternatively, you can paste the Choreo samples repository URL in the Provide Repository URL field to connect to it without requiring authorization from the Choreo Apps GitHub application. However, authorizing the repository with the Choreo GitHub App is necessary if you want to enable Auto Deploy for the component.

    -
    -

    Note

    -

    The Choreo GitHub App requires the following permissions:

    -
      -
    • Read and write access to code and pull requests.
      • -
    • Read access to issues and metadata.
      • -
    -

    You can revoke access if you do not want Choreo to have access to your GitHub account. However, write access is exclusively utilized for sending pull requests to a user repository. Choreo will not directly push any changes to a repository.

    -
    -
    7. -
  7. -

    Under Connect Your Repository, enter the following information:

    - - - - - - - - - - - - - - - - - - - - - -
    FieldValue
    OrganizationYour GitHub account
    Repositorychoreo-samples
    Branchmain
    -
    8. -
  8. -

    Select Docker as the buildpack.

    -
    9. -
  9. -

    Enter the following information:

    - - - - - - - - - - - - - - - - - -
    FieldValue
    Docker Context/greeting-service-go
    Dockerfile/greeting-service-go/Dockerfile
    -
    -

    Info

    -
      -
    1. -

      To successfully build your container with Choreo, it is essential to explicitly define a user ID (UID) under the USER instruction in your Dockerfile. For reference, see sample Dockerfile. -To ensure that the defined USER instruction is valid, it must conform to the following conditions:

      -
        -
      • A valid User ID is a numeric value between 10000-20000, such as 10001 or 10500.
        • -
      • Usernames are considered invalid and should not be used. For example, my-custom-user-12221 or my-custom-user are invalid User IDs.
        • -
      -
      2. -
    2. -

      The Dockerfile used in this guide is a multi-stage Dockerfile, which is designed to keep the final image size small and provides the ability to build the application with a specific version of tools and libraries.

      -
      3. -
    -
    -
    10. -
  10. -

    Click Create. This creates the component and takes you to the Overview page of the component.

    -
    11. -
-

You have successfully created a service from a Dockerfile. Next, you can build and deploy the service.

-

Step 2: Build and deploy

-

Now that we have connected the source repository, and configured the endpoint details, it's time to build the service and create an image. Then we can deploy that image test the greeter service.

-

Step 2.1: Build

-

To build the service, follow these steps:

-
    -
  1. In the left navigation menu, click Build.
    2. -
  2. -

    On the Build page, click Build Latest.

    -
    -

    Note

    -

    Building the service component may take a while. You can track the progress via the logs in the Build Details pane. Once the build process is complete, the build status changes to Success.

    -
    -

    You can access the following scans under Build.

    -
      -
    • The Dockerfile scan: Choreo performs a scan to check if a non-root user ID is assigned to the Docker container to ensure security. If no non-root user is specified, the build will fail.
      • -
    • Container (Trivy) vulnerability scan: This detects vulnerabilities in the final docker image.
      • -
    • -

      Container (Trivy) vulnerability scan: The details of the vulnerabilities open in a separate pane. If this scan detects critical vulnerabilities, the build will fail.

      -
      -

      Info

      -

      If you have Choreo environments on a private data plane, you can ignore these vulnerabilities and proceed with the deployment.

      -
      -
      • -
    -
    3. -
-

Step 2.2: Deploy

-

To deploy the service, follow these steps:

-
    -
  1. In the left navigation menu, click Deploy.
    2. -
  2. On the Set Up card, click Configure & Deploy.
    3. -
  3. In the Environment Configurations pane that opens, click Next to skip the configuration.
    4. -
  4. In the File Mount pane, click Next to skip the configuration.
    5. -
  5. -

    Review the Endpoint Details and click Deploy.

    -
    -

    Note

    -

    Deploying the service component may take a while. Once deployed, the Development environment card indicates the Deployment Status as Active.

    -
    -
    6. -
-

Once you have successfully deployed the service, you can test, manage, and observe it like any other component type in Choreo.

-

To perform a more detailed diagnosis of this Dockerfile-based REST API by viewing Kubernetes-level insights, see Choreo's DevOps capabilities.

- - - - - - -
-
- - -
- - - -
- - -
- - - -
-
-
- - - - - - - - - - - - - - - - - \ No newline at end of file diff --git a/en/site/develop-components/develop-services/develop-a-service/index.html b/en/site/develop-components/develop-services/develop-a-service/index.html deleted file mode 100644 index 4d0b0032f..000000000 --- a/en/site/develop-components/develop-services/develop-a-service/index.html +++ /dev/null @@ -1,3438 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - Develop a Service - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- - - -
- - - - - - -
- - -
- -
- - - - - - - -
-
- - - -
-
-
- - - - -
-
-
- - - -
-
-
- - - -
-
-
- - - -
-
- - - - - - - - - - - - - - - - - - - - -

Develop a Service

-

Choreo allows you to create and deploy applications in your preferred programming language.

-

In this guide, you will:

-
    -
  • Build a simple greeting service using a sample service implementation. The sample implementation will have a single resource named greet that accepts a single query parameter as input.
    • -
  • Deploy the service in Choreo using a Go buildpack. The service will run on port 9090.
    • -
  • Test the service.
    • -
-

Prerequisites

-

Before you try out this guide, complete the following:

-
    -
  • -

    If you are signing in to the Choreo Console for the first time, create an organization as follows:

    -
      -
    1. Go to https://console.choreo.dev/, and sign in using your preferred method.
      2. -
    2. Enter a unique organization name. For example, Stark Industries.
      3. -
    3. Read and accept the privacy policy and terms of use.
      4. -
    4. Click Create.
      5. -
    -

    This creates the organization and opens the Project Home page of the default project created for you.

    -
    • -
  • -

    Fork the Choreo samples repository, which contains the sample greetings service implementation in Go.

    -
    • -
-

Learn the repository file structure

-

It is important to understand the purpose of the key files in the sample service. The following table provides a brief overview of each file in the greeter service:

-
-

Note

-

The specified file paths are relative to <sample-repository-dir>/greeting-service-go

-
- - - - - - - - - - - - - - - - - - - - - -
FilepathDescription
main.goThe Go-based greeter service code.
.choreo/endpoints.yamlChoreo-specific configuration that provides information about how Choreo exposes the service.
openapi.yamlThe OpenAPI contract of the greeter service. This is required to publish the service as a managed API. This openapi.yaml file is referenced by the .choreo/endpoints.yaml file.
-

Let's get started!

-

Configure the service port with endpoints

-

In Choreo, you can expose your services via endpoints.

-

You are going to run the greeter service on port 9090. To securely expose the service through Choreo, you must provide the port and other required information to Choreo. For detailed information on each attribute of an endpoint, see Configure Endpoints.

-

To configure the endpoint details of a containerized component, Choreo looks for an endpoints.yaml file inside the .choreo directory. Be sure to place the .choreo directory at the root of the Docker build context path.

-

In the greeter sample, the endpoints.yaml file is in the greeting-service-go/.choreo/ directory.

-

Step 1: Create a service component

-

To create a containerized service component, follow these steps:

-
    -
  1. Go to https://console.choreo.dev/ and sign in. This opens the project home page.
    2. -
  2. If you already have one or more components in your project, click + Create. Otherwise, proceed to the next step.
    3. -
  3. Click the Service card.
    4. -
  4. -

    Enter a display name, a unique name, and a description for the service component. You can enter the values given below:

    -
    -

    Info

    -

    In the Component Name field, you must specify a name to uniquely identify the component in various contexts. The value is editable only at the time you create the component. You cannot change the name after you create the component.

    -
    - - - - - - - - - - - - - - - - - - - - - -
    FieldValue
    Component Display NameGreetings
    Component Namegreetings
    DescriptionSend greetings
    -
    5. -
  5. -

    Go to the GitHub tab.

    -
    6. -
  6. -

    To allow Choreo to connect to your GitHub account, click Authorize with GitHub. If you have not already connected your GitHub repository to Choreo, enter your GitHub credentials and select the repository you created in the prerequisites section to install the Choreo GitHub App.

    -

    Alternatively, you can paste the Choreo samples repository URL in the Provide Repository URL field to connect to it without requiring authorization from the Choreo Apps GitHub application. However, authorizing the repository with the Choreo GitHub App is necessary if you want to enable Auto Deploy for the component.

    -
    -

    Note

    -

    The Choreo GitHub App requires the following permissions:

    -
      -
    • Read and write access to code and pull requests.
      • -
    • Read access to issues and metadata.
      • -
    -

    You can revoke access if you do not want Choreo to have access to your GitHub account. However, write access is exclusively utilized for sending pull requests to a user repository. Choreo will not directly push any changes to a repository.

    -
    -
    7. -
  7. -

    Under Connect Your Repository, enter the following information:

    - - - - - - - - - - - - - - - - - - - - - -
    FieldValue
    OrganizationYour GitHub account
    GitHub Repositorychoreo-samples
    Branchmain
    -
    8. -
  8. -

    Select Go as the buildpack.

    -
    9. -
  9. -

    Enter the following information:

    - - - - - - - - - - - - - - - - - -
    FieldValue
    Go Project Directory/greeting-service-go
    Language Version1.x
    -
    10. -
  10. -

    Click Create. This creates the component and lists it under Component Listing on the project home page.

    -
    11. -
-

You have successfully created the service. The next step is to build and deploy it.

-

Step 2: Build and deploy

-

Now that you have connected the source repository and configured the endpoint details, it's time to build and deploy the greeter service.

-

Step 2.1: Build

-

To build the service, follow these steps:

-
    -
  1. On the project home page, click on the Greetings component you created. This takes you to the component overview page.
    2. -
  2. In the left navigation menu, click Build.
    3. -
  3. -

    On the Build page, click Build Latest.

    -
    -

    Note

    -

    Building the service component may take a while. You can track the progress via the logs in the Build Details pane. Once the build process is complete, the build status changes to Success.

    -
    -
    4. -
-

Step 2.2: Deploy

-

To deploy the service, follow these steps:

-
    -
  1. In the left navigation menu, click Deploy.
    2. -
  2. On the Set Up card, click Configure & Deploy.
    3. -
  3. In the Environment Configurations pane that opens, click Next to skip the configuration.
    4. -
  4. In the File Mount pane, click Next to skip the configuration.
    5. -
  5. -

    Review the Endpoint Details and click Deploy.

    -
    -

    Note

    -

    Deploying the service component may take a while. Once deployed, the Development environment card indicates the Deployment Status as Active.

    -
    -
    6. -
-

Once you have successfully deployed the service, you can test, manage, and observe it like any other component type in Choreo.

- - - - - - -
-
- - -
- - - -
- - -
- - - -
-
-
- - - - - - - - - - - - - - - - - \ No newline at end of file diff --git a/en/site/develop-components/develop-services/develop-a-tcp-service/index.html b/en/site/develop-components/develop-services/develop-a-tcp-service/index.html deleted file mode 100644 index 91f68706d..000000000 --- a/en/site/develop-components/develop-services/develop-a-tcp-service/index.html +++ /dev/null @@ -1,15 +0,0 @@ - - - - - - Redirecting... - - - - - - -Redirecting... - - diff --git a/en/site/develop-components/develop-services/develop-a-udp-service/index.html b/en/site/develop-components/develop-services/develop-a-udp-service/index.html deleted file mode 100644 index 35acff85f..000000000 --- a/en/site/develop-components/develop-services/develop-a-udp-service/index.html +++ /dev/null @@ -1,15 +0,0 @@ - - - - - - Redirecting... - - - - - - -Redirecting... - - diff --git a/en/site/develop-components/develop-services/expose-a-ballerina-graphql-endpoint-via-a-service/index.html b/en/site/develop-components/develop-services/expose-a-ballerina-graphql-endpoint-via-a-service/index.html deleted file mode 100644 index 3632e9a94..000000000 --- a/en/site/develop-components/develop-services/expose-a-ballerina-graphql-endpoint-via-a-service/index.html +++ /dev/null @@ -1,3525 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - Expose a Ballerina GraphQL Endpoint via a Service - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- - - -
- - - - - - -
- - -
- -
- - - - - - - -
-
- - - -
-
-
- - - - -
-
-
- - - -
-
-
- - - -
-
-
- - - -
-
- - - - - - - - - - - - - - - - - - - - -

Expose a Ballerina GraphQL Endpoint via a Service

-

Choreo offers the flexibility to develop and deploy applications in a language of your preference. This guide shows you how to deploy a service component that exposes a GraphQL API using the Ballerina language in Choreo. No prior knowledge of the Ballerina language is required to follow this guide.

-

GraphQL API is a query language and runtime that provides a single endpoint for retrieving flexible and efficient data in a strongly-typed and self-documenting way. By following this guide, you will build a service component in Ballerina and deploy it on Choreo for any GraphQL client application to utilize it.

-

This guide shows how to build a simple reading list service and deploy it in Choreo using Ballerina. The GraphQL endpoint you create in this guide has two operations: Query and Mutation. The Query type operations read the data in the data source, and the Mutation operations update the data in the data source. The reading list service has two queries and three mutations as follows:

-

Queries

-

Retrieve the reading list

-

This resource accepts an optional filter, status, which filters the reading list by reading status. Accepted values for status are reading, read, and to_read.

-

Sample request: -

$ curl -X POST -H "Content-Type: application/json" -d '{"query": "query {allBooks (status: \"reading\") { id title author status }}"}' http://localhost:8090
-

-

Sample response -

$ {
-  "data": {
-    "allBooks": [
-      {
-        "id": 1,
-        "title": "Sample Book",
-        "author": "Test Author",
-        "status": "to_read"
-      }
-    ]
-  }
-}
-

-

Retrieve a book item from the reading list

-

This resource accepts a filter, id, which will select the book item from the reading list by book id. The id is an Integer value.

-

Sample request -

$ curl -X POST -H "Content-Type: application/json" -d '{"query": "query {book (id: 1) { id title author status }}"}' http://localhost:8090
-

-

Sample response -

$ {
-  "data": {
-    "book": {
-      "id": 1,
-      "title": "Sample Book",
-      "author": "Test Author",
-      "status": "to_read"
-    }
-  }
-}
-

-

Mutations

-

Add a book item to the reading list

-

This remote function accepts a book record as the input and consists of the title and the author. When you add a new book to the reading list, the method updates the reading status of the newly added book to to_read. This method returns the added book item upon successful execution.

-

Sample request

-
$ curl -X POST -H "Content-type: application/json" -d '{ "query": "mutation { addBook(book: {title: \"Sample Book\", author: \"Test Author\"}) { id title author status } }" }' 'http://localhost:8090'
-
- -

Sample response

-
$ {
-  "data": {
-    "addBook": {
-      "id": 1,
-      "title": "Sample Book",
-      "author": "Test Author",
-      "status": "to_read"
-    }
-  }
-}
-
- -

Update the reading status of a book

-

This remote function requires id and status as inputs to update the reading status of the selected book. The id refers to the id of the book. It is an integer. The status refers to the reading status that needs to be updated. This method returns the updated book item upon successful execution.

-

Sample request

-
$ curl -X POST -H "Content-type: application/json" -d '{ "query": "mutation { setStatus(id: 1, status: \"reading\") { id title author status } }" }' 'http://localhost:8090'
-
- -

Sample response

-
$ {
-  "data": {
-    "setStatus": {
-      "id": 1,
-      "title": "Sample Book",
-      "author": "Test Author",
-      "status": "reading"
-    }
-  }
-}
-
- -

Delete a book item from the reading list

-

This remote function requires the id as the input to delete the book item from the reading list. This method returns the removed book item upon successful execution.

-

Sample request

-
$ curl -X POST -H "Content-type: application/json" -d '{ "query": "mutation { deleteBook(id: 1) { id title author status } }" }' 'http://localhost:8090'
-
- -

Sample response -

$ {
-  "data": {
-    "deleteBook": {
-      "id": 1,
-      "title": "Sample Book",
-      "author": "Test Author",
-      "status": "reading"
-    }
-  }
-}
-

-

Our next step is to set up the resources that you will require to follow the guide, including the sample reading list application and the Choreo GitHub app.

-

Prerequisites

-
    -
  • -

    If you are signing in to the Choreo Console for the first time, create an organization as follows:

    -
      -
    1. Go to https://console.choreo.dev/, and sign in using your preferred method.
      2. -
    2. Enter a unique organization name. For example, Stark Industries.
      3. -
    3. Read and accept the privacy policy and terms of use.
      4. -
    4. Click Create.
      5. -
    -

    This creates the organization and opens the Project Home page of the default project created for you.

    -
    • -
  • -

    Fork the Choreo samples repository, which contains the sample GraphQL service implementation for this guide.

    -
    • -
-

Let's get started!

-

Learn the repository file structure

-

It is important to understand the purpose of the key files in the sample service. The following table provides a brief overview of each file in the reading list service.

-
-

Note

-

The following file paths are relative to the path <sample-repository-dir>/reading-list-graphql.

-
- - - - - - - - - - - - - - - - - - - - - -
FilepathDescription
service.balThe reading list service code written in the Ballerina language.
Ballerina.tomlThe Ballerina configuration file.
.choreo/endpoints.yamlThe configuration file with endpoint details.
-

Step 1: Create a service component

-

To create a Ballerina service component, follow these steps:

-
    -
  1. Go to https://console.choreo.dev/ and sign in. This opens the project home page.
    2. -
  2. If you already have one or more components in your project, click + Create. Otherwise, proceed to the next step.
    3. -
  3. Click the Service card.
    4. -
  4. -

    Enter a display name, a unique name, and a description for the service component. You can enter the values given below:

    -
    -

    Info

    -

    In the Component Name field, you must specify a name to uniquely identify the component in various contexts. The value is editable only at the time you create the component. You cannot change the name after you create the component.

    -
    - - - - - - - - - - - - - - - - - - - - - -
    FieldValue
    Component Display NameBallerina Reading List
    Component Nameballerina-reading-list
    DescriptionManage a reading list
    -
    5. -
  5. -

    Click the GitHub tab.

    -
    6. -
  6. -

    To allow Choreo to connect to your GitHub account, click Authorize with GitHub. If you have not already connected your GitHub repository to Choreo, enter your GitHub credentials and select the repository you created in the prerequisites section to install the Choreo GitHub App.

    -

    Alternatively, you can paste the Choreo samples repository URL in the Provide Repository URL field to connect to it without requiring authorization from the Choreo Apps GitHub application. However, authorizing the repository with the Choreo GitHub App is necessary if you want to enable Auto Deploy for the component.

    -
    -

    Note

    -

    The Choreo GitHub App requires the following permissions:

    -
      -
    • Read and write access to code and pull requests.
      • -
    • Read access to issues and metadata.
      • -
    -

    You can revoke access if you do not want Choreo to have access to your GitHub account. However, write access is exclusively utilized for sending pull requests to a user repository. Choreo will not directly push any changes to a repository.

    -
    -
    7. -
  7. -

    Under Connect Your Repository, enter the following information:

    - - - - - - - - - - - - - - - - - - - - - -
    FieldValue
    OrganizationYour GitHub account
    GitHub Repositorychoreo-samples
    Branchmain
    -
    8. -
  8. -

    Select Ballerina as the buildpack.

    -
    9. -
  9. -

    Enter the following information:

    - - - - - - - - - - - - - -
    FieldValue
    Ballerina Project Directoryreading-list-graphql
    -
    10. -
  10. -

    Click Create. This creates the component and takes you to the Overview page of the component.

    -
    11. -
-

You have successfully created a service component that exposes a GraphQL API written in the Ballerina language. Next, let's build and deploy the service.

-

Step 2: Build and deploy

-

Now that we have connected the source repository, it's time to build and deploy the reading list service.

-

Step 2.1: Build

-

To build the service, follow these steps:

-
    -
  1. In the left navigation menu, click Build.
    2. -
  2. -

    On the Build page, click Build Latest.

    -
    -

    Note

    -

    Building the service component may take a while. You can track the progress via the logs in the Build Details pane. Once the build process is complete, the build status changes to Success.

    -
    -
    3. -
-

Step 2.2: Deploy

-

To deploy the service, follow these steps:

-
    -
  1. In the left navigation menu, click Deploy.
    2. -
  2. On the Set Up card, click Configure & Deploy.
    3. -
  3. In the Configurations pane that opens, click Next to skip the configuration.
    4. -
  4. -

    Review the Endpoint Details and click Deploy.

    -
    -

    Note

    -

    Deploying the service component may take a while. Once deployed, the Development environment card indicates the Deployment Status as Active.

    -
    -

    To build and deploy the service, follow the steps below:

    -
    5. -
-

Once you have successfully deployed your service, you can test, manage, and observe it like any other component type in Choreo.

-

For detailed instructions, see the following sections:

- - - - - - - -
-
- - -
- - - -
- - -
- - - -
-
-
- - - - - - - - - - - - - - - - - \ No newline at end of file diff --git a/en/site/develop-components/develop-services/expose-a-grpc-endpoint-via-a-service/index.html b/en/site/develop-components/develop-services/expose-a-grpc-endpoint-via-a-service/index.html deleted file mode 100644 index cf0f18ccf..000000000 --- a/en/site/develop-components/develop-services/expose-a-grpc-endpoint-via-a-service/index.html +++ /dev/null @@ -1,3745 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - Expose a gRPC Endpoint via a Service - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- - - -
- - - - - - -
- - -
- -
- - - - - - - -
-
- - - -
-
-
- - - - -
-
-
- - - -
-
-
- - - -
-
-
- - - -
-
- - - - - - - - - - - - - - - - - - - - -

Expose a gRPC Endpoint via a Service

-

Choreo allows you to create and deploy applications in your preferred programming language. One powerful option is gRPC, a high-performance and language-agnostic remote procedure call (RPC) framework. It utilizes Protocol Buffers to define services and generate client/server code.

-

In this guide, you will learn to use Choreo to create a service component that exposes a gRPC server implemented in Go, enabling efficient and scalable communication with any gRPC client application. No prior knowledge of the Go language is necessary to follow this guide.

-

By following this guide, you will:

-
    -
  • Create a simple gRPC server using a Service component.
    • -
  • -

    Link the containerized gRPC service to the Choreo component using the Dockerfile. - The greeter service has a single RPC method named sayHello. Following is the proto file the server and the client application are using:

    -
    syntax = "proto3";
-option go_package = "github.com/wso2/choreo-samples/go-grpc/pkg";
-
-service greeter {
-  rpc SayHello (HelloRequest) returns (HelloReply) {}
-}
-
-message HelloRequest {
-  string name = 1;
-}
-
-message HelloReply {
-  string message = 1;
-}
-
    - -
    • -
  • -

    Deploy the gRPC server component in Choreo.

    -
    • -
  • Create a gRPC client using a Manual Trigger component.
    • -
  • Deploy the gRPC client.
    • -
  • Invoke the gRPC server using a gRPC client and check the response through the Choreo log view.
    • -
-

Prerequisites

-

Before you try out this guide, complete the following:

-
    -
  • -

    If you are signing in to the Choreo Console for the first time, create an organization as follows:

    -
      -
    1. Go to https://console.choreo.dev/, and sign in using your preferred method.
      2. -
    2. Enter a unique organization name. For example, Stark Industries.
      3. -
    3. Read and accept the privacy policy and terms of use.
      4. -
    4. Click Create.
      5. -
    -

    This creates the organization and opens the Project Home page of the default project created for you.

    -
    • -
  • -

    Fork the Choreo samples repository, which contains the sample service implementation for this guide.

    -
    • -
-

Let's get started!

-

Learn the repository file structure

-

It is important to understand the purpose of the key files in the sample service. The following table provides a brief overview of each file in the greeter service.

-
-

Note

-

The following file paths are relative to the path <sample-repository-dir>/go-grpc.

-
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
File PathDescription
main.goThe greeter service code written in the Go language.
greeter_client/main.goThe greeter client application written in the Go language.
Dockerfile.serverThe Dockerfile to build the container image of the server application.
Dockerfile.clientThe Dockerfile to build the container image of the client application.
.choreo/endpoints.yamlThe Choreo-specific configuration that provides information about how Choreo exposes the service.
pkg/greeter.protoThe interface definition of the gRPC service. This is used to generate the server and client stubs for the Go application.
-

Configure the service port with endpoints

-

In Choreo, you can expose your services via endpoints.

-

Let's run the gRPC server service component on port 8080. To securely expose the service through Choreo, you must provide the port and other required information to Choreo. For detailed information on each attribute of an endpoint, see Configure Endpoints.

-

Choreo looks for an endpoints.yaml file inside the .choreo directory to configure the endpoint details of the containerized component. Ensure the .choreo directory is at the root of the Docker build context path.

-

In the gRPC server sample, the endpoints.yaml file is at go-grpc/.choreo/endpoints.yaml, where the build context path is go-grpc.

-

Step 1: Create a service component with a gRPC endpoint

-

To create a containerized service component, follow these steps:

-
    -
  1. Go to https://console.choreo.dev/ and sign in. This opens the project home page.
    2. -
  2. If you already have one or more components in your project, click + Create. Otherwise, proceed to the next step.
    3. -
  3. Click the Service card.
    4. -
  4. -

    Enter a display name, a unique name, and a description for the service component. You can enter the values given below:

    -
    -

    Info

    -

    In the Component Name field, you must specify a name to uniquely identify the component in various contexts. The value is editable only at the time you create the component. You cannot change the name after you create the component.

    -
    - - - - - - - - - - - - - - - - - - - - - -
    FieldValue
    Component Display NameGo gRPC Server
    Component Namego-grpc-server
    DescriptionSend greetings
    -
    5. -
  5. -

    Click the GitHub tab.

    -
    6. -
  6. -

    To allow Choreo to connect to your GitHub account, click Authorize with GitHub. If you have not already connected your GitHub repository to Choreo, enter your GitHub credentials and select the repository you created in the prerequisites section to install the Choreo GitHub App.

    -

    Alternatively, you can paste the Choreo samples repository URL in the Provide Repository URL field to connect to it without requiring authorization from the Choreo Apps GitHub application. However, authorizing the repository with the Choreo GitHub App is necessary if you want to enable Auto Deploy for the component.

    -
    -

    Note

    -

    The Choreo GitHub App requires the following permissions:

    -
      -
    • Read and write access to code and pull requests.
      • -
    • Read access to issues and metadata.
      • -
    -

    You can revoke access if you do not want Choreo to have access to your GitHub account. However, write access is exclusively utilized for sending pull requests to a user repository. Choreo will not directly push any changes to a repository.

    -
    -
    7. -
  7. -

    Under Connect Your Repository, enter the following information:

    - - - - - - - - - - - - - - - - - - - - - -
    FieldValue
    OrganizationYour GitHub account
    GitHub Repositorychoreo-samples
    Branchmain
    -
    8. -
  8. -

    Select Docker as the buildpack.

    -
    9. -
  9. -

    Enter the following information:

    - - - - - - - - - - - - - - - - - -
    FieldValue
    Docker Contextgo-grpc
    Dockerfilego-grpc/Dockerfile.server
    -
    -

    Info

    -
      -
    1. -

      To successfully build your container with Choreo, it is essential to explicitly define a User ID (UID) under the USER instruction in your Dockerfile. For reference, see the sample Dockerfile. -To ensure that the defined USER instruction is valid, it must conform to the following conditions:

      -
        -
      • A valid User ID is a numeric value between 10000-20000, such as 10001 or 10500.
        • -
      • Usernames are considered invalid and should not be used. For example, my-custom-user-12221 or my-custom-user are invalid User IDs.
        • -
      -
      2. -
    2. -

      The Dockerfile utilized in this guide is a multi-stage Dockerfile, which is designed to keep the final image size small and provides the ability to build the application with a specific version of tools and libraries.

      -
      3. -
    -
    -
    10. -
  10. -

    Click Create. This creates the component and takes you to the Overview page of the component.

    -
    11. -
-

You have successfully created a service from a Dockerfile. Next, you can build and deploy the service.

-

Step 2: Build and deploy

-

Now that you have connected the source repository, and configured the endpoint details, it's time to build the service and create an image. Then you can deploy the image and test the greeter service.

-

Step 2.1: Build

-

To build the service, follow these steps:

-
    -
  1. In the left navigation menu, click Build.
    2. -
  2. -

    On the Build page, click Build Latest.

    -
    -

    Note

    -

    Building the service component may take a while. You can track the progress via the logs in the Build Details pane. Once the build process is complete, the build status changes to Success.

    -
    -

    You can access the following scans under Build.

    -
      -
    • The Dockerfile scan: Choreo performs a scan to check if a non-root user ID is assigned to the Docker container to ensure security. If no non-root user is specified, the build will fail.
      • -
    • Container (Trivy) vulnerability scan: This detects vulnerabilities in the final docker image.
      • -
    • -

      Container (Trivy) vulnerability scan: The details of the vulnerabilities open in a separate pane. If this scan detects critical vulnerabilities, the build will fail.

      -
      -

      Info

      -

      If you have Choreo environments on a private data plane, you can ignore these vulnerabilities and proceed with the deployment.

      -
      -
      • -
    -
    3. -
-

Step 2.2: Deploy

-

To deploy the service, follow these steps:

-
    -
  1. In the left navigation menu, click Deploy.
    2. -
  2. On the Set Up card, click Configure & Deploy.
    3. -
  3. In the Environment Configurations pane that opens, click Next to skip the configuration.
    4. -
  4. In the File Mount pane, click Next to skip the configuration.
    5. -
  5. -

    Review the Endpoint Details and click Deploy.

    -
    -

    Note

    -

    Deploying the service component may take a while. Once deployed, the Development environment card indicates the Deployment Status as Active.

    -
    -
    6. -
  6. -

    Once you have successfully deployed your service, navigate to the component overview page and copy the gRPC service URL. You need to provide that URL when setting up the client application later in this guide.

    -
    7. -
-

You have successfully deployed the gRPC server. Currently, the gRPC service is only accessible by the components deployed within the same project.

-

Step 3: Invoke the gRPC service

-

Let's invoke the gRPC service that you created above, using a gRPC client.

-

Step 3.1: Create a manual task for the gRPC client

-

To create a manual task component, follow these steps:

-
    -
  1. On the Choreo Console header, click the Project list and select the project where you created the gRPC service component. This opens the project home page.
    2. -
  2. Go to the Component Listing section and click + Create.
    3. -
  3. Click the Manual Task card.
    4. -
  4. -

    Enter a display name, a unique name, and a description for the component. You can enter the values given below:

    -
    -

    Info

    -

    In the Component Name field, you must specify a name to uniquely identify the component in various contexts. The value is editable only at the time you create the component. You cannot change the name after you create the component.

    -
    - - - - - - - - - - - - - - - - - - - - - -
    FieldValue
    Component Display NameGo gRPC Client
    Component Namego-grpc-client
    DescriptionReceive greetings
    -
    5. -
  5. -

    Click the GitHub tab.

    -
    6. -
  6. -

    To allow Choreo to connect to your GitHub account, click Authorize with GitHub. If you have not already connected your GitHub repository to Choreo, enter your GitHub credentials and select the repository you created in the prerequisites section to install the Choreo GitHub App.

    -

    Alternatively, you can paste the Choreo samples repository URL in the Provide Repository URL field to connect to it without requiring authorization from the Choreo Apps GitHub application. However, authorizing the repository with the Choreo GitHub App is necessary if you want to enable Auto Deploy for the component.

    -
    -

    Note

    -

    The Choreo GitHub App requires the following permissions:

    -
      -
    • Read and write access to code and pull requests.
      • -
    • Read access to issues and metadata.
      • -
    -

    You can revoke access if you do not want Choreo to have access to your GitHub account. However, write access is exclusively utilized for sending pull requests to a user repository. Choreo will not directly push any changes to a repository.

    -
    -
    7. -
  7. -

    Under Connect Your Repository, enter the following information:

    - - - - - - - - - - - - - - - - - - - - - -
    FieldValue
    OrganizationYour GitHub account
    GitHub Repositorychoreo-samples
    Branchmain
    -
    8. -
  8. -

    Select Docker as the buildpack.

    -
    9. -
  9. -

    Enter the following information:

    - - - - - - - - - - - - - - - - - -
    FieldValue
    Docker Contextgo/grpc
    Dockerfilego/grpc/Dockerfile.client
    -
    10. -
  10. -

    Click Create. This creates the component and takes you to the Overview page of the component.

    -
    11. -
-

Step 3.2: Build the gRPC client component

-

To build the component, follow these steps:

-
    -
  1. In the left navigation menu, click Build.
    2. -
  2. -

    On the Build page, click Build Latest.

    -
    -

    Note

    -

    Building the service component may take a while. You can track the progress via the logs in the Build Details pane. Once the build process is complete, the build status changes to Success.

    -
    -
    3. -
-

Step 3.3: Setup environment variables and deploy the gRPC client

-

The client application, in this case, the gRPC client, requires the server URL of the gRPC server service. This is read from the client application as an environment variable. Follow the steps below to configure the environment variable for the client application:

-
    -
  1. On the Choreo Console left navigation menu, click Deploy.
    2. -
  2. In the Set Up card, click Configure & Deploy.
    3. -
  3. In the Environment Configurations pane that opens, click + Add.
    4. -
  4. -

    Specify the following name and value to configure the environment variable for the client application:

    - - - - - - - - - - - - - - - - - -
    FieldValue
    NameGREETER_SERVICE
    ValuePaste the URL value copied after deploying the gRPC service via step 2.2 above. Make sure to drop the http:// or grpc:// part and the trailing / from the URL when copying. For example, if the URL is http://go-grpc-server-3192360657:8080/, add only go-grpc-server-3192360657:8080.
    -
    5. -
  5. -

    Click Add and then click Next.

    -
    6. -
  6. Click Deploy.
    7. -
-

Step 3.4: Execute the gRPC client component

-

To execute the gRPC client, follow these steps:

-
    -
  1. In the left navigation menu, click Execute.
    2. -
  2. Click Run Now. This triggers the gRPC client and generates logs. - You can trigger multiple runs to generate multiple logs.
    3. -
-

For details on what you can monitor via the execute page, see Monitor executions.

- - - - - - -
-
- - -
- - - -
- - -
- - - -
-
-
- - - - - - - - - - - - - - - - - \ No newline at end of file diff --git a/en/site/develop-components/develop-services/expose-a-tcp-server-via-a-service/index.html b/en/site/develop-components/develop-services/expose-a-tcp-server-via-a-service/index.html deleted file mode 100644 index be1ebb744..000000000 --- a/en/site/develop-components/develop-services/expose-a-tcp-server-via-a-service/index.html +++ /dev/null @@ -1,3727 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - Expose a TCP Server via a Service - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- - - -
- - - - - - -
- - -
- -
- - - - - - - -
-
- - - -
-
-
- - - - -
-
-
- - - -
-
-
- - - -
-
-
- - - -
-
- - - - - - - - - - - - - - - - - - - - -

Expose a TCP Server via a Service

-

Choreo offers the flexibility to design and deploy applications in the programming language of your choice. One viable choice for specific network communication needs is TCP (Transmission Control Protocol). TCP provides a reliable, stream-oriented communication mechanism that ensures data integrity and orderliness during transmission. It's the go-to option for scenarios where guaranteed data delivery and error recovery are paramount.

-

In this guide, you will learn to use Choreo to create a service component that exposes a TCP server implemented in Go, enabling efficient and scalable communication with any TCP client application. No prior knowledge of the Go language is necessary to follow this guide.

-

By following this guide, you will:

-
    -
  • Setup a TCP server
      -
    • Create a simple TCP server using a service component.
      • -
    • Link the containerized TCP service to the Choreo component using a Dockerfile.
      • -
    • Deploy the TCP server component in Choreo.
      • -
    -
    • -
  • Setup a TCP client
      -
    • Create a TCP client using a manual task component.
      • -
    • Link the containerized TCP client to the Choreo component using a Dockerfile.
      • -
    • Deploy the TCP client component in Choreo.
      • -
    -
    • -
  • Invoke the TCP server using a TCP client and observe the response through the Choreo log view.
    • -
-

Prerequisites

-

Before you try out this guide, complete the following:

-
    -
  • -

    If you are signing in to the Choreo Console for the first time, create an organization as follows:

    -
      -
    1. Go to https://console.choreo.dev/, and sign in using your preferred method.
      2. -
    2. Enter a unique organization name. For example, Stark Industries.
      3. -
    3. Read and accept the privacy policy and terms of use.
      4. -
    4. Click Create.
      5. -
    -

    This creates the organization and opens the Project Home page of the default project created for you.

    -
    • -
  • -

    Fork the Choreo samples repository, which contains the sample service implementation for this guide.

    -
    • -
-

Let's get started!

-

Learn the repository file structure

-

It is important to understand the purpose of the key files in the sample service. The following table provides a brief overview of each file in the sample service.

-
-

Note

-

The following file paths are relative to the path <sample-repository-dir>/docker-tcp-service.

-
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
File PathDescription
server/main.goThe greeter service code written in the Go language.
client/main.goThe greeter client application written in the Go language.
Dockerfile.serverThe Dockerfile to build the container image of the server application.
Dockerfile.clientThe Dockerfile to build the container image of the client application.
.choreo/endpoints.yamlThe Choreo-specific configuration provides information about how Choreo exposes the service.
-

Configure the service port with endpoints

-

In Choreo, you can expose your services via endpoints.

-

Let's run the TCP server service component on port 5050. To securely expose the service through Choreo, you must provide the port and other required information to Choreo. For detailed information on each attribute of an endpoint, see Configure Endpoints.

-

Choreo looks for an endpoints.yaml file inside the .choreo directory to configure the endpoint details of a containerized component. Place the .choreo directory at the root of the Docker build context path.

-

In our TCP server sample, the endpoints.yaml file is at docker-tcp-service/.choreo/endpoints.yaml, where the build context path is docker-tcp-service.

-

Step 1: Create a service component with a TCP endpoint

-

To create a containerized service component, follow these steps:

-
    -
  1. Go to https://console.choreo.dev/ and sign in. This opens the project home page.
    2. -
  2. If you already have one or more components in your project, click + Create. Otherwise, proceed to the next step.
    3. -
  3. Click the Service card.
    4. -
  4. -

    Enter a display name, a unique name, and a description for the service component. You can enter the values given below:

    -
    -

    Info

    -

    In the Component Name field, you must specify a name to uniquely identify the component in various contexts. The value is editable only at the time you create the component. You cannot change the name after you create the component.

    -
    - - - - - - - - - - - - - - - - - - - - - -
    FieldValue
    Component Display NameGo TCP Server
    Component Namego-tcp-server
    DescriptionSend greetings
    -
    5. -
  5. -

    Click the GitHub tab.

    -
    6. -
  6. -

    To allow Choreo to connect to your GitHub account, click Authorize with GitHub. If you have not already connected your GitHub repository to Choreo, enter your GitHub credentials and select the repository you created in the prerequisites section to install the Choreo GitHub App.

    -

    Alternatively, you can paste the Choreo samples repository URL in the Provide Repository URL field to connect to it without requiring authorization from the Choreo Apps GitHub application. However, authorizing the repository with the Choreo GitHub App is necessary if you want to enable Auto Deploy for the component.

    -
    -

    Note

    -

    The Choreo GitHub App requires the following permissions:

    -
      -
    • Read and write access to code and pull requests.
      • -
    • Read access to issues and metadata.
      • -
    -

    You can revoke access if you do not want Choreo to have access to your GitHub account. However, write access is exclusively utilized for sending pull requests to a user repository. Choreo will not directly push any changes to a repository.

    -
    -
    7. -
  7. -

    Under Connect Your Repository, enter the following information:

    - - - - - - - - - - - - - - - - - - - - - -
    FieldValue
    OrganizationYour GitHub account
    GitHub Repositorychoreo-samples
    Branchmain
    -
    8. -
  8. -

    Select Docker as the buildpack.

    -
    9. -
  9. -

    Enter the following information:

    - - - - - - - - - - - - - - - - - -
    FieldValue
    Docker Contextdocker-tcp-service
    Dockerfiledocker-tcp-service/Dockerfile.server
    -
    -

    Info

    -
      -
    1. -

      To successfully build your container with Choreo, it is essential to explicitly define a User ID (UID) under the USER instruction in your Dockerfile. For reference, see the sample Dockerfile. -To ensure that the defined USER instruction is valid, it must conform to the following conditions:

      -
        -
      • A valid User ID is a numeric value between 10000-20000, such as 10001 or 10500.
        • -
      • Usernames are considered invalid and should not be used. For example, my-custom-user-12221 or my-custom-user are invalid User IDs.
        • -
      -
      2. -
    2. -

      The Dockerfile utilized in this guide is a multi-stage Dockerfile, which is designed to keep the final image size small and provides the ability to build the application with a specific version of tools and libraries.

      -
      3. -
    -
    -
    10. -
  10. -

    Click Create. This creates the component and takes you to the Overview page of the component.

    -
    11. -
-

You have successfully created a service from a Dockerfile. Next, you can build and deploy the service.

-

Step 2: Build and deploy

-

Now that you have connected the source repository, and configured the endpoint details, it's time to build the service and create an image. Then you can deploy the image and test the service.

-

Step 2.1: Build

-

To build the service, follow these steps:

-
    -
  1. In the left navigation menu, click Build.
    2. -
  2. -

    On the Build page, click Build Latest.

    -
    -

    Note

    -

    Building the service component may take a while. You can track the progress via the logs in the Build Details pane. Once the build process is complete, the build status changes to Success.

    -
    -

    You can access the following scans under Build.

    -
      -
    • The Dockerfile scan: Choreo performs a scan to check if a non-root user ID is assigned to the Docker container to ensure security. If no non-root user is specified, the build will fail.
      • -
    • Container (Trivy) vulnerability scan: This detects vulnerabilities in the final docker image.
      • -
    • -

      Container (Trivy) vulnerability scan: The details of the vulnerabilities open in a separate pane. If this scan detects critical vulnerabilities, the build will fail.

      -
      -

      Info

      -

      If you have Choreo environments on a private data plane, you can ignore these vulnerabilities and proceed with the deployment.

      -
      -
      • -
    -
    3. -
-

Step 2.2: Deploy

-

To deploy the service, follow these steps:

-
    -
  1. In the left navigation menu, click Deploy.
    2. -
  2. On the Set Up card, click Configure & Deploy.
    3. -
  3. In the Environment Configurations pane that opens, click Next to skip the configuration.
    4. -
  4. In the File Mount pane, click Next to skip the configuration.
    5. -
  5. -

    Review the Endpoint Details and click Deploy.

    -
    -

    Note

    -

    Deploying the service component may take a while. Once deployed, the Development environment card indicates the Deployment Status as Active.

    -
    -
    6. -
  6. -

    Once you have successfully deployed your service, navigate to the component overview page and copy the TCP service address. You need to provide that address when setting up the client application later in this guide.

    -
    7. -
-

You have successfully deployed the TCP server. Currently, the TCP service is only accessible by the components deployed within the same project.

-

Step 3: Invoke the TCP service

-

Now let's use a TCP client to invoke the TCP service that you created above. To do this, you can create a manual trigger component as the TCP client. This is the recommended approach because, in this example, it's more efficient to have a client that connects to the server, sends a request, and then stops. Here, a continuously executing task isn't required. Furthermore, if you use a manual trigger component, you won't need to expose an endpoint in the client for invocation, unlike with an API.

-

Step 3.1: Create a manual trigger for the TCP client

-

To create a manual task component, follow these steps:

-
    -
  1. On the Choreo Console header, click the Project list and select the project where you created the TCP service component. This opens the project home page.
    2. -
  2. Go to the Component Listing section and click + Create.
    3. -
  3. Click the Manual Task card.
    4. -
  4. -

    Enter a display name, a unique name, and a description for the component. You can enter the values given below:

    -
    -

    Info

    -

    In the Component Name field, you must specify a name to uniquely identify the component in various contexts. The value is editable only at the time you create the component. You cannot change the name after you create the component.

    -
    - - - - - - - - - - - - - - - - - - - - - -
    FieldValue
    Component Display NameGo TCP Client
    Component Namego-tcp-client
    DescriptionReceive greetings
    -
    5. -
  5. -

    Click the GitHub tab.

    -
    6. -
  6. -

    To allow Choreo to connect to your GitHub account, click Authorize with GitHub. If you have not already connected your GitHub repository to Choreo, enter your GitHub credentials and select the repository you created in the prerequisites section to install the Choreo GitHub App.

    -

    Alternatively, you can paste the Choreo samples repository URL in the Provide Repository URL field to connect to it without requiring authorization from the Choreo Apps GitHub application. However, authorizing the repository with the Choreo GitHub App is necessary if you want to enable Auto Deploy for the component.

    -
    -

    Note

    -

    The Choreo GitHub App requires the following permissions:

    -
      -
    • Read and write access to code and pull requests.
      • -
    • Read access to issues and metadata.
      • -
    -

    You can revoke access if you do not want Choreo to have access to your GitHub account. However, write access is exclusively utilized for sending pull requests to a user repository. Choreo will not directly push any changes to a repository.

    -
    -
    7. -
  7. -

    Under Connect Your Repository, enter the following information:

    - - - - - - - - - - - - - - - - - - - - - -
    FieldValue
    OrganizationYour GitHub account
    GitHub Repositorychoreo-samples
    Branchmain
    -
    8. -
  8. -

    Select Docker as the buildpack.

    -
    9. -
  9. -

    Enter the following information:

    - - - - - - - - - - - - - - - - - -
    FieldValue
    Docker Contextdocker-tcp-service
    Dockerfiledocker-tcp-service/Dockerfile.client
    -
    10. -
  10. -

    Click Create. This creates the component and takes you to the Overview page of the component.

    -
    11. -
-

Step 3.2: Build the TCP client component

-

To build the component, follow these steps:

-
    -
  1. In the left navigation menu, click Build.
    2. -
  2. -

    On the Build page, click Build Latest.

    -
    -

    Note

    -

    Building the service component may take a while. You can track the progress via the logs in the Build Details pane. Once the build process is complete, the build status changes to Success.

    -
    -
    3. -
-

Step 3.3: Setup environment variables and deploy the TCP client

-

The client application, in this case, the TCP client, requires the server URL of the TCP server service. This is read from the client application as an environment variable. Follow the steps below to configure the environment variable for the client application:

-
    -
  1. On the Choreo Console left navigation menu, click Deploy.
    2. -
  2. In the Set Up card, click Configure & Deploy.
    3. -
  3. In the Environment Configurations pane that opens, click + Add.
    4. -
  4. -

    Specify the following name and value to configure the environment variable for the client application:

    - - - - - - - - - - - - - - - - - -
    FieldValue
    NameSERVER_ADDRESS
    ValuePaste the URL value copied after deploying the TCP service via step 2.2 above. Make sure to drop the tcp:// part and the trailing / from the URL when copying. For example, add only go-tcp-server-1097922445:8080.
    -
    5. -
  5. -

    Click Add and then click Next.

    -
    6. -
  6. Click Deploy.
    7. -
-

Step 3.4: Execute the TCP client component

-

To execute the TCP client, follow these steps:

-
    -
  1. In the left navigation menu, click Execute.
    2. -
  2. Click Run Now. This triggers the TCP client and generates logs. - You can trigger multiple runs to generate multiple logs.
    3. -
-

For details on what you can monitor via the execute page, see Monitor executions.

- - - - - - -
-
- - -
- - - -
- - -
- - - -
-
-
- - - - - - - - - - - - - - - - - \ No newline at end of file diff --git a/en/site/develop-components/develop-services/expose-a-udp-server-via-a-service/index.html b/en/site/develop-components/develop-services/expose-a-udp-server-via-a-service/index.html deleted file mode 100644 index 30b3ad94b..000000000 --- a/en/site/develop-components/develop-services/expose-a-udp-server-via-a-service/index.html +++ /dev/null @@ -1,3727 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - Expose a UDP Server via a Service - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- - - -
- - - - - - -
- - -
- -
- - - - - - - -
-
- - - -
-
-
- - - - -
-
-
- - - -
-
-
- - - -
-
-
- - - -
-
- - - - - - - - - - - - - - - - - - - - -

Expose a UDP Server via a Service

-

Choreo offers the flexibility to design and deploy applications in the programming language of your choice. One compelling choice for certain network communication needs is UDP (User Datagram Protocol). UDP is a high-speed, connectionless protocol ideal for scenarios where lightweight, real-time data transmission is essential.

-

In this guide, you will learn to use Choreo to create a Service component that exposes a UDP server implemented in Go, enabling efficient and scalable communication with any UDP client application. No prior knowledge of the Go language is necessary to follow this guide.

-

By following this guide, you will:

-
    -
  • Setup a UDP server
      -
    • Create a simple UDP server using a Service component.
      • -
    • Link the containerized UDP service to the Choreo component using the Dockerfile.
      • -
    • Deploy the UDP server component in Choreo.
      • -
    -
    • -
  • Setup a UDP client
      -
    • Create a UDP client using a manual task component.
      • -
    • Link the containerized UDP client to the Choreo component using the Dockerfile.
      • -
    • Deploy the UDP client component in Choreo.
      • -
    -
    • -
  • Invoke the UDP server using a UDP client and check the response through the Choreo log view.
    • -
-

Prerequisites

-

Before you try out this guide, complete the following:

-
    -
  • -

    If you are signing in to the Choreo Console for the first time, create an organization as follows:

    -
      -
    1. Go to https://console.choreo.dev/, and sign in using your preferred method.
      2. -
    2. Enter a unique organization name. For example, Stark Industries.
      3. -
    3. Read and accept the privacy policy and terms of use.
      4. -
    4. Click Create.
      5. -
    -

    This creates the organization and opens the Project Home page of the default project created for you.

    -
    • -
  • -

    Fork the Choreo samples repository, which contains the sample service implementation for this guide.

    -
    • -
-

Let's get started!

-

Learn the repository file structure

-

It is important to understand the purpose of the key files in the sample service. The following table provides a brief overview of each file in the sample service.

-
-

Note

-

The following file paths are relative to the path <sample-repository-dir>/docker-udp-service.

-
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
File PathDescription
server/main.goThe greeter service code written in the Go language.
client/main.goThe greeter client application written in the Go language.
Dockerfile.serverThe Dockerfile to build the container image of the server application.
Dockerfile.clientThe Dockerfile to build the container image of the client application.
.choreo/endpoints.yamlThe Choreo-specific configuration provides information about how Choreo exposes the service.
-

Configure the service port with endpoints

-

In Choreo, you can expose your services via endpoints.

-

Let's run the UDP server service component on port 5050. To securely expose the service through Choreo, you must provide the port and other required information to Choreo. For detailed information on each attribute of an endpoint, see Configure Endpoints.

-

Choreo looks for an endpoints.yaml file inside the .choreo directory to configure the endpoint details of a containerized component. Place the .choreo directory at the root of the Docker build context path.

-

In our gRPC server sample, the endpoints.yaml file is at docker-udp-service/.choreo/endpoints.yaml, where the build context path is docker-udp-service.

-

Step 1: Create a service component with a UDP endpoint

-

To create a containerized service component, follow these steps:

-
    -
  1. Go to https://console.choreo.dev/ and sign in. This opens the project home page.
    2. -
  2. If you already have one or more components in your project, click + Create. Otherwise, proceed to the next step.
    3. -
  3. Click the Service card.
    4. -
  4. -

    Enter a display name, a unique name, and a description for the service component. You can enter the values given below:

    -
    -

    Info

    -

    In the Component Name field, you must specify a name to uniquely identify the component in various contexts. The value is editable only at the time you create the component. You cannot change the name after you create the component.

    -
    - - - - - - - - - - - - - - - - - - - - - -
    FieldValue
    Component Display NameGo UDP Server
    Component Namego-udp-server
    DescriptionSend greetings
    -
    5. -
  5. -

    Click the GitHub tab.

    -
    6. -
  6. -

    To allow Choreo to connect to your GitHub account, click Authorize with GitHub. If you have not already connected your GitHub repository to Choreo, enter your GitHub credentials and select the repository you created in the prerequisites section to install the Choreo GitHub App.

    -

    Alternatively, you can paste the Choreo samples repository URL in the Provide Repository URL field to connect to it without requiring authorization from the Choreo Apps GitHub application. However, authorizing the repository with the Choreo GitHub App is necessary if you want to enable Auto Deploy for the component.

    -
    -

    Note

    -

    The Choreo GitHub App requires the following permissions:

    -
      -
    • Read and write access to code and pull requests.
      • -
    • Read access to issues and metadata.
      • -
    -

    You can revoke access if you do not want Choreo to have access to your GitHub account. However, write access is exclusively utilized for sending pull requests to a user repository. Choreo will not directly push any changes to a repository.

    -
    -
    7. -
  7. -

    Under Connect Your Repository, enter the following information:

    - - - - - - - - - - - - - - - - - - - - - -
    FieldValue
    OrganizationYour GitHub account
    GitHub Repositorychoreo-samples
    Branchmain
    -
    8. -
  8. -

    Select Docker as the buildpack.

    -
    9. -
  9. -

    Enter the following information:

    - - - - - - - - - - - - - - - - - -
    FieldValue
    Docker Contextdocker-udp-service
    Dockerfiledocker-udp-service/Dockerfile.server
    -
    -

    Info

    -
      -
    1. -

      To successfully build your container with Choreo, it is essential to explicitly define a User ID (UID) under the USER instruction in your Dockerfile. For reference, see the sample Dockerfile. -To ensure that the defined USER instruction is valid, it must conform to the following conditions:

      -
        -
      • A valid User ID is a numeric value between 10000-20000, such as 10001 or 10500.
        • -
      • Usernames are considered invalid and should not be used. For example, my-custom-user-12221 or my-custom-user are invalid User IDs.
        • -
      -
      2. -
    2. -

      The Dockerfile utilized in this guide is a multi-stage Dockerfile, which is designed to keep the final image size small and provides the ability to build the application with a specific version of tools and libraries.

      -
      3. -
    -
    -
    10. -
  10. -

    Click Create. This creates the component and takes you to the Overview page of the component.

    -
    11. -
-

You have successfully created a service from a Dockerfile. Next, you can build and deploy the service.

-

Step 2: Build and deploy

-

Now that you have connected the source repository, and configured the endpoint details, it's time to build the service and create an image. Then you can deploy the image and test the service.

-

Step 2.1: Build

-

To build the service, follow these steps:

-
    -
  1. In the left navigation menu, click Build.
    2. -
  2. -

    On the Build page, click Build Latest.

    -
    -

    Note

    -

    Building the service component may take a while. You can track the progress via the logs in the Build Details pane. Once the build process is complete, the build status changes to Success.

    -
    -

    You can access the following scans under Build.

    -
      -
    • The Dockerfile scan: Choreo performs a scan to check if a non-root user ID is assigned to the Docker container to ensure security. If no non-root user is specified, the build will fail.
      • -
    • Container (Trivy) vulnerability scan: This detects vulnerabilities in the final docker image.
      • -
    • -

      Container (Trivy) vulnerability scan: The details of the vulnerabilities open in a separate pane. If this scan detects critical vulnerabilities, the build will fail.

      -
      -

      Info

      -

      If you have Choreo environments on a private data plane, you can ignore these vulnerabilities and proceed with the deployment.

      -
      -
      • -
    -
    3. -
-

Step 2.2: Deploy

-

To deploy the service, follow these steps:

-
    -
  1. In the left navigation menu, click Deploy.
    2. -
  2. On the Set Up card, click Configure & Deploy.
    3. -
  3. In the Environment Configurations pane that opens, click Next to skip the configuration.
    4. -
  4. In the File Mount pane, click Next to skip the configuration.
    5. -
  5. -

    Review the Endpoint Details and click Deploy.

    -
    -

    Note

    -

    Deploying the service component may take a while. Once deployed, the Development environment card indicates the Deployment Status as Active.

    -
    -
    6. -
  6. -

    Once you have successfully deployed your service, navigate to the component overview page and copy the UDP service address. You must provide that address when setting up the client application later in this guide.

    -
    7. -
-

You have successfully deployed the UDP server. Currently, the UDP service is only accessible by the components deployed within the same project.

-

Step 3: Invoke the UDP service

-

Now let's use a UDP client to invoke the UDP service that you created above. To do this, you can create a manual trigger component as the UDP client. This is the recommended approach because, in this example, it's more efficient to have a client that connects to the server, sends a request, and then stops. Here, a continuously executing task isn't required. Furthermore, if you use a manual trigger component, you won't need to expose an endpoint in the client for invocation, unlike with an API.

-

Step 3.1: Create a manual trigger for the UDP client

-

To create a manual task component, follow these steps:

-
    -
  1. On the Choreo Console header, click the Project list and select the project where you created the UDP service component. This opens the project home page.
    2. -
  2. Go to the Component Listing section and click + Create.
    3. -
  3. Click the Manual Task card.
    4. -
  4. -

    Enter a display name, a unique name, and a description for the component. You can enter the values given below:

    -
    -

    Info

    -

    In the Component Name field, you must specify a name to uniquely identify the component in various contexts. The value is editable only at the time you create the component. You cannot change the name after you create the component.

    -
    - - - - - - - - - - - - - - - - - - - - - -
    FieldValue
    Component Display NameGo UDP Client
    Component Namego-udp-client
    DescriptionReceive greetings
    -
    5. -
  5. -

    Click the GitHub tab.

    -
    6. -
  6. -

    To allow Choreo to connect to your GitHub account, click Authorize with GitHub. If you have not already connected your GitHub repository to Choreo, enter your GitHub credentials and select the repository you created in the prerequisites section to install the Choreo GitHub App.

    -

    Alternatively, you can paste the Choreo samples repository URL in the Provide Repository URL field to connect to it without requiring authorization from the Choreo Apps GitHub application. However, authorizing the repository with the Choreo GitHub App is necessary if you want to enable Auto Deploy for the component.

    -
    -

    Note

    -

    The Choreo GitHub App requires the following permissions:

    -
      -
    • Read and write access to code and pull requests.
      • -
    • Read access to issues and metadata.
      • -
    -

    You can revoke access if you do not want Choreo to have access to your GitHub account. However, write access is exclusively utilized for sending pull requests to a user repository. Choreo will not directly push any changes to a repository.

    -
    -
    7. -
  7. -

    Under Connect Your Repository, enter the following information:

    - - - - - - - - - - - - - - - - - - - - - -
    FieldValue
    OrganizationYour GitHub account
    GitHub Repositorychoreo-samples
    Branchmain
    -
    8. -
  8. -

    Select Docker as the buildpack.

    -
    9. -
  9. -

    Enter the following information:

    - - - - - - - - - - - - - - - - - -
    FieldValue
    Docker Contextdocker-udp-service
    Dockerfiledocker-udp-service/Dockerfile.client
    -
    10. -
  10. -

    Click Create. This creates the component and takes you to the Overview page of the component.

    -
    11. -
-

Step 3.2: Build the UDP client component

-

To build the component, follow these steps:

-
    -
  1. In the left navigation menu, click Build.
    2. -
  2. -

    On the Build page, click Build Latest.

    -
    -

    Note

    -

    Building the service component may take a while. You can track the progress via the logs in the Build Details pane. Once the build process is complete, the build status changes to Success.

    -
    -
    3. -
-

Step 3.3: Setup environment variables and deploy the UDP client

-

The client application, in this case, the UDP client, requires the server URL of the UDP server service. This is read from the client application as an environment variable. Follow the steps below to configure the environment variable for the client application:

-
    -
  1. On the Choreo Console left navigation menu, click Deploy.
    2. -
  2. In the Set Up card, click Configure & Deploy.
    3. -
  3. In the Environment Configurations pane that opens, click + Add.
    4. -
  4. -

    Specify the following name and value to configure the environment variable for the client application:

    - - - - - - - - - - - - - - - - - -
    FieldValue
    NameSERVER_ADDRESS
    ValuePaste the URL value copied after deploying the UDP service via step 2.2 above. Make sure to drop the udp:// part and the trailing / from the URL when copying. For example, add only go-udp-server-1097922445:8080.
    -
    5. -
  5. -

    Click Add and then click Next.

    -
    6. -
  6. Click Deploy.
    7. -
-

Step 3.4: Execute the UDP client component

-

To execute the UDP client, follow these steps:

-
    -
  1. In the left navigation menu, click Execute.
    2. -
  2. Click Run Now. This triggers the UDP client and generates logs. - You can trigger multiple runs to generate multiple logs.
    3. -
-

For details on what you can monitor via the execute page, see Monitor executions.

- - - - - - -
-
- - -
- - - -
- - -
- - - -
-
-
- - - - - - - - - - - - - - - - - \ No newline at end of file diff --git a/en/site/develop-components/develop-services/service-component-overview/index.html b/en/site/develop-components/develop-services/service-component-overview/index.html deleted file mode 100644 index 108520f56..000000000 --- a/en/site/develop-components/develop-services/service-component-overview/index.html +++ /dev/null @@ -1,3626 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - Service Component Overview - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- - - -
- - - - - - -
- - -
- -
- - - - - - - -
-
- - - -
-
-
- - - - -
-
-
- - - -
-
-
- - - -
-
-
- - - -
-
- - - - - - - - - - - - - - - - - - - - -

Service Component Overview

-

Explore how to create, deploy, manage, and observe service components in Choreo.

-

What is a service component?

-

A service component in Choreo lets you deploy and expose REST, GraphQL, gRPC, UDP, or TCP services. It is a fundamental building block for creating cloud-native applications in Choreo. They provide a simple and effective way to expose functionality as a service to other components within Choreo or to the outside world.

-

Service components encapsulate business logic and provide standardized interfaces, called endpoints, for communicating with other components or systems. You can deploy and scale services independently, which makes them highly flexible and adaptable to changing workloads.

-

With the help of the service component, developers can quickly create APIs and microservices, making it easier to implement and manage complex software systems. Service components can also be integrated with other Choreo components, that acts as message processors, connectors, and data sources, etc to create powerful end-to-end solutions.

-

Services and integrations are exposed to other services, integrations, or applications through endpoints. A service or an integration can expose multiple endpoints, each representing a unique entry point into the service. For example, a service may expose a REST API endpoint and a GraphQL endpoint, each providing different ways to interact with the service. Endpoints provide specific details for how the service or the integration can be consumed. For instance, the port number, protocol, and the schema such as open API specification (OAS) or GraphQL schema. By defining these details, endpoints make it possible for other services, integrations, and applications to discover and interact with the service in a standardized way.

-

Choreo defines endpoints by combining port binding, protocol, endpoint name, network visibility, endpoint schema, and additional protocol-related fields. The following table describes each attribute of an endpoint.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldDescription
NameA unique identifier for the endpoint within the service component.
PortThe network port on which the endpoint is accessible.
TypeThe endpoint protocol. Supported protocols: REST, GraphQL, gRPC, UDP, and TCP.
Network VisibilityDetermines the level of visibility of an endpoint. Possible values are:
  • Project: Allows components within the same project to access the endpoint.
  • Organization: Allows any component within the same organization to access the endpoint but restricts access to components outside the organization.
  • Public: Allows any client to access the endpoint, regardless of location or organization.
SchemaSpecifies the structure and format of the data exchanged through the endpoint.
Context (HTTP and GraphQL only)A context path that you add to the endpoint's URL for routing purposes.
-

Configure endpoints

-

The method of defining endpoints depends on the buildpack. For buildpacks other than Ballerina and WSO2 MI, it is required to have an endpoints.yaml file in project root directory to create the Service component.

-

Configure endpoints with buildpacks (except Ballerina)

-

When you build a service component using any other buildpacks(Java, Python, NodeJS, Ruby, PHP, Go, Dockerfile, etc) other than Ballerina and WSO2 MI, you can configure the endpoint details with the endpoints.yaml configuration file. You must place this file inside the .choreo directory at the build context path and commit it to the source repository.

-

See Understanding the endpoints.yaml file to learn about the endpoints.yaml file.

-

Configure endpoints with the Ballerina buildpack

-

When you create a service component with the Ballerina buildpack, Choreo automatically detects the endpoint details for REST APIs. You can override the auto-generated endpoint configuration by providing the endpoints.yaml file in the source directory.

-
-

Note

-

Automatic endpoint generation is not supported for dynamic endpoint parameters such as variable ports. Therefore, you must use an endpoint.yaml file to define dynamic endpoint parameters.

-
-

See Understanding the endpoints.yaml file to learn about the endpoints.yaml file.

-

Learn the endpoints.yaml file

-

The endpoints.yaml file has a specific structure and contains the following details:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldRequiredDescription
versionRequiredThe version of the endpoints.yaml file.
nameRequiredA unique name for the endpoint, which Choreo will use to generate the managed API.
portRequiredThe numeric port value that gets exposed via this endpoint.
typeRequiredThe type of traffic this endpoint is accepting, such as REST, GraphQL, gRPC, UDPor TCP. Currently, the MI preset supports only the REST type.
networkVisibilityRequiredThe network level visibility of this endpoint, which defaults to Public if not specified. Accepted values are Project, Organization, or Public.
contextRequiredThe context (base path) of the API that Choreo exposes via this endpoint.
schemaFilePathRequiredThe 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.
-

Sample endpoints.yaml

-

File location:

-
<docker-build-context-path>/.choreo/endpoints.yaml
-
- -
-

Note

-
    -
  • -

    For components built with Ballerina buildpack docker-build-context-path should be replaced with component-root. -For example: <component-root>/.choreo/endpoints.yaml

    -
    • -
  • -

    For components built with WSO2 MI buildpack docker-build-context-path should be replaced with <Project Path>. -For example: <Project Path>/.choreo/endpoints.yaml

    -
    • -
-
-

File content:

-
# +required Version of the endpoint configuration YAML
-version: 0.1
-
-# +required List of endpoints to create
-endpoints:
-  # +required Unique name for the endpoint. (This name will be used when generating the managed API)
-- name: Greeting Service
-  # +required Numeric port value that gets exposed via this endpoint
-  port: 9090
-  # +required Type of the traffic this endpoint is accepting. Example: REST, GraphQL, etc.
-  # Allowed values: REST, GraphQL, GRPC, UDP, TCP
-  type: REST
-  # +optional Network level visibility of this endpoint. Defaults to Public
-  # Accepted values: Project|Organization|Public.
-  networkVisibility: Project
-  # +optional Context (base path) of the API that is exposed via this endpoint.
-  # This is mandatory if the endpoint type is set to REST or GraphQL.
-  context: /greeting
-  # +optional Path to the schema definition file. Defaults to wild card route if not provided
-  # This is only applicable to REST endpoint types.
-  # The path should be relative to the docker context.
-  schemaFilePath: greeting_openapi.yaml
-
- -

Apply advanced component connection configurations

-

The component-config.yaml file extends the capabilities of endpoints.yaml by introducing enhancements that allow you to apply advanced inbound and outbound connection configurations.

-
-

Beta release

-
    -
  • The current version of the component-config.yaml file is considered stable. However, it is important to note that the configuration schema may undergo changes and improvements based on user feedback.
    • -
  • Support for the current schema will remain even when new versions are introduced.
    • -
-
-

The component-config.yaml file complements and enhances the existing endpoint configuration process. It allows you to define how your service's endpoints (inbound connections) are exposed and how your service connects to external services or components (outbound connections).

-
    -
  • -

    Inbound configurations: This configuration section is for you to define inbound connections, Similar to endpoints.yaml, you can define how your service endpoints are exposed. It aligns seamlessly with the existing endpoint schema structure.

    -
    • -
  • -

    Outbound configurations: This configuration section is for you to specify outbound connection details, including service connections. The Choreo Internal Marketplace facilitates creating connections with existing services. To learn more about Choreo Marketplace, see Choreo Marketplace.

    -
    • -
-
-

Note

-
    -
  • If both component-config.yaml and endpoints.yaml are defined in the .choreo path, the component-config.yaml file takes priority.
    • -
  • Outbound connections are not supported for deprecated components and WSO2 MI buildpack components.
    • -
-
-

Learn the component-config.yaml file

-

The component-config.yaml file has a specific structure and contains the following details:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldRequiredDescription
apiVersionRequiredThe version of the component-config.yaml file defaults to core.choreo.dev/v1beta1.
kindRequiredThe resource type of the file defaults to ComponentConfig.
spec.inboundOptionalThe list of inbound connection configurations.
spec.outboundOptionalThe list of outbound connection configurations.
-

Inbound connection configurations (spec.inbound)

-

In the spec.inbound configuration section, you can specify endpoints to set up inbound connections. To specify endpoints, you can follow the existing endpoints schema structure. For details on the endpoints schema structure, see the endpoints schema documentation.

-

Outbound connection configurations (spec.outbound)

-

In the spec.outbound section, you can define serviceReferences. To define serviceReferences, you can use the service references generated in the Internal Marketplace when creating a service connection. To copy the outbound connection configurations, see the inline developer guide that is available when you create a connection.

-

The serviceReferences schema has a specific structure and contains the following details:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldRequiredDescription
nameRequiredA unique name for the service reference.
connectionConfigRequiredA unique name for the connection instance.
envOptionalThe list of environment variable mappings that get injected into the container.
env.fromRequiredThe key name of the connection configuration.
env.toRequiredThe environment variable that gets injected into the container.
-
-

Note

-

Choreo automatically generates outbound connection configurations upon the creation of a connection within the internal marketplace. The properties such as name, connectionConfig, and env.from are automatically generated. However, you must manually set the env.to value.

-
-

Sample component-config.yaml

-

File location:

-
<docker-build-context-path>/.choreo/component-config.yaml
-
- -
-

Note

-
    -
  • For components built using the Ballerina buildpack, you must replace docker-build-context-path with the component-root. -For example, <component-root>/.choreo/component-config.yaml.
    • -
  • For components built using the WSO2 MI buildpack, you must replace docker-build-context-path with the <Project Path>. -For example, <Project Path>/.choreo/component-config.yaml.
    • -
-
-

File content:

-
apiVersion: core.choreo.dev/v1beta1
-kind: ComponentConfig
-spec:
-  # +optional Incoming connection details for the component (AKA endpoints).
-  inbound:
-    # +required Unique name for the endpoint. (This name will be used when generating the managed API)
-    - name: Greeting Service
-      # +required Numeric port value that gets exposed via the endpoint
-      port: 9090
-      # +required Type of traffic that the endpoint is accepting. For example: REST, GraphQL, etc.
-      # Allowed values: REST, GraphQL, GRPC, TCP, UDP.
-      type: REST
-      # +optional Network level visibility of the endpoint. Defaults to Public
-      # Accepted values: Project|Organization|Public.
-      networkVisibility: Public
-      # +optional Context (base path) of the API that gets exposed via the endpoint.
-      # This is mandatory if the endpoint type is set to REST or GraphQL.
-      context: /greeting
-      # +optional The path to the schema definition file. Defaults to wildcard route if not specified.
-      # This is only applicable to REST endpoint types.
-      # The path should be relative to the Docker context.
-      schemaFilePath: greeting_openapi.yaml
-  # +optional Outgoing connection details for the component.
-  outbound:
-    # +optional Defines the service references from the Internal Marketplace.
-    serviceReferences:
-      # +required Name of the service reference.
-      - name: choreo:///apifirst/mttm/mmvhxd/ad088/v1.0/PUBLIC
-        # +required Name of the connection instance.
-        connectionConfig: 19d2648b-d29c-4452-afdd-1b9311e81412
-        # +optional Environment variables injected to the component for connection configuration.
-        env:
-          # +required Key name of the connection configuration.
-          - from: ServiceURL
-            # +required Environment variable injected to the container.
-            to: SERVICE_URL
-
- -

Expose endpoints as managed APIs

-

Exposing endpoints as managed APIs is crucial to ensure secure and controlled access to the services being exposed. When a user wants to expose their written service to the outside world or to the organization at large, there is an inherent security risk involved. To mitigate this risk, the Choreo platform is built with an internal (access within the organization only) or external (publicly accessible) gateway that is protected with Choreo API management making the services secure by design.

-
-

Note

-

This feature is not available for gRPC, UDP, and TCP endpoints.

-
-

If you want to expose an endpoint as a managed API in Choreo, you need to set the network visibility to either Organization or Public. This allows the endpoint to be exposed through the Choreo API Gateway, which provides a number of benefits, including:

-
    -
  • Expose APIs to external and internal consumers
    • -
  • Full lifecycle API Management
    • -
  • API throttling
    • -
  • Secure APIs with industry-standard authorization flows
    • -
  • API analytics and monitoring
    • -
-

Once you deploy the service component, Choreo will expose the endpoint as a managed API through the Choreo API Gateway. You can then use the full lifecycle API management features provided by Choreo to test, deploy, maintain, monitor, and manage your API using the API management features.

-

Understand the default component URL

-

The default URL of a component corresponds to the default endpoint of the component and is structured as follows:

-

<domain>/<project-name>/<component-name>

-

This URL does not include the default endpoint name. For all other endpoints, the URL structure includes the endpoint name, as follows:

-

<domain>/<project-name>/<component-name>/<endpoint-name>

-

If a component has multiple endpoints, Choreo allows you to change the endpoint corresponding to the default component URL. For a component with a single endpoint, the default URL automatically corresponds to that endpoint.

-

Change the default endpoint of a component

-

To change the default endpoint of a component, follow the steps given below:

-
-

Note

-
    -
  • You cannot change the default endpoint if it has associated published APIs. You must go to the Lifecycle page and unpublish the relevant APIs before updating the default endpoint. For instructions on unpublishing an API, see Lifecycle Management.
    • -
  • Choreo does not allow you to change the default endpoint of a component if you create multiple deployment tracks within its current major version, or promote the component beyond its initial environment.
    • -
-
-
    -
  1. Sign in to the Choreo Console.
    2. -
  2. In the Component Listing pane, click on the component for which you want to change the default endpoint.
    3. -
  3. In the left navigation menu, click Deploy.
    4. -
  4. On the Deploy page, go to the Set Up card and click Configure & Deploy.
    5. -
  5. In the Environment Configurations pane that opens, click Next.
    6. -
  6. In the File Mount pane that opens, click Next.
    7. -
  7. In the Endpoint Details pane that opens, click the Default Endpoint list, select the endpoint you want to set as the default endpoint, and then click Update.
    8. -
  8. Click Deploy. This deploys the component with the selected endpoint as the default, and the default URL will now correspond to this endpoint.
    9. -
- - - - - - -
-
- - -
- - - -
- - -
- - - -
-
-
- - - - - - - - - - - - - - - - - \ No newline at end of file diff --git a/en/site/develop-components/develop-web-applications/build-and-deploy-a-single-page-web-application/index.html b/en/site/develop-components/develop-web-applications/build-and-deploy-a-single-page-web-application/index.html deleted file mode 100644 index f1b5fd4d3..000000000 --- a/en/site/develop-components/develop-web-applications/build-and-deploy-a-single-page-web-application/index.html +++ /dev/null @@ -1,3499 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - Build and Deploy a Single-Page Web Application - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- - - -
- - - - - - -
- - -
- -
- - - - - - - -
-
- - - -
-
-
- - - - -
-
-
- - - -
-
-
- - - -
-
-
- - - -
-
- - - - - - - - - - - - - - - - - - - - -

Build and Deploy a Single-Page Web Application

-

A web application is an application program hosted on a server and serves ingress traffic through a browser. In Choreo, you can deploy a web application by creating a Web Application component and connecting it to a Git repository that contains the implementation of the web application. Web applications can fall into one of the following categories:

-
    -
  • Single page applications (SPAs): Examples include React, Angular, Vue, Svelte, etc.
    • -
  • Web servers: These serve static content or provide server-side rendering/static site generation (SSR/SSG).
    • -
  • Static content: Examples include websites and other static resources that do not require a backend, usually comprising static HTML/JS/CSS files.
    • -
-

Prerequisites

-
    -
  • To deploy a Web Application component, you must have a GitHub account with a repository containing the web application's implementation. For this guide, fork the https://github.com/wso2/choreo-samples repository, which contains the sample web application implementation.
    • -
-

Create a web application

-

You can create a web application in Choreo as follows:

-
    -
  • -

    Build and deploy a SPA from the source code.

    -
      -
    • Create a Web Application component by connecting a repository that includes the web application source code.
      • -
    • Select the relevant buildpack. Default buildpacks include React, Angular, and Vue.js. If you are using a different SPA framework, you can try one of these buildpacks because the configurations can be overridden to support most Javascript-based SPAs.
      • -
    • Enter the build command based on your package manager. - NPM, yarn, and pnpm are supported and the relevant package manager is run based on the dependency lock file in your repository (defaults to NPM if no lock file is present).
      • -
    • Specify the build output directory.
      • -
    • Specify the NodeJS version. Choreo does not pick the Nodejs version from the package.json engine property. The required Node version must be explicitly set in the build configuration.
      • -
    -

    Once you create the Web Application component, Choreo automatically generates a build pipeline for your single-page application and deploys it.

    -
    • -
  • -

    Bring your Dockerfile.

    -
      -
    • Create a Web Application component by connecting a repository that contains the Dockerfile for your containerized web application.
      • -
    • Commit a Dockerfile to your connected git repository to have full control over your build process.
      • -
    -

    This approach is recommended if you are deploying a web server and not just a single-page application (or a single-page application with a complex build process).

    -
    • -
  • -

    Host static websites.

    -
      -
    • To host static web content, you can create a Web Application component and connect it to the GitHub repository that contains the required static assets.
      • -
    • Select the Static Websites buildpack. This buildpack does not trigger a build process. It only fetches the files from the path specified in the repository and serves as it is.
      • -
    -
    • -
-

Now let's take a look at how you can build and deploy a SPA from source code:

-

Follow the steps below to create a sample Web Application component and deploy it in Choreo:

-
    -
  1. Sign in to the Choreo Console at https://console.choreo.dev/login/. This opens the Project Home page.
    2. -
  2. If you already have one or more components in your project, click + Create. Otherwise, proceed to the next step.
    3. -
  3. Click the Web Application card.
    4. -
  4. This opens the Create a Web Application pane, where you can specify a name and description for the component. Enter a unique name and description.
    5. -
  5. Go to the GitHub tab.
    6. -
  6. -

    To allow Choreo to connect to your GitHub account, click Authorize with GitHub. If you have not already connected your GitHub repository to Choreo, enter your GitHub credentials and select the repository you created in the prerequisites section to install the Choreo GitHub App.

    -

    Alternatively, you can paste the Choreo samples repository URL in the Provide Repository URL field to connect to it without requiring authorization from the Choreo Apps GitHub application. However, authorizing the repository with the Choreo GitHub App is necessary if you want to enable Auto Deploy for the component.

    -
    -

    Note

    -

    The Choreo GitHub App requires the following permissions:

    -
      -
    • Read and write access to code and pull requests.
      • -
    • Read access to issues and metadata.
      • -
    -

    You can revoke access if you do not want Choreo to have access to your GitHub account. However, write access is exclusively utilized for sending pull requests to a user repository. Choreo will not directly push any changes to a repository.

    -
    -
    7. -
  7. -

    Enter the following information:

    - - - - - - - - - - - - - - - - - - - - - -
    FieldDescription
    GitHub AccountYour account
    GitHub Repositorychoreo-samples
    Branchmain
    -
    8. -
  8. -

    Select React as the Buildpack.

    -
    9. -
  9. -

    Enter the following information:

    - - - - - - - - - - - - - - - - - - - - - - - - - -
    FieldDescription
    Project Directory/react-single-page-app
    Build Commandnpm run build
    Build Pathbuild
    Node Version18
    -
    -

    Tip

    -

    Managed authentication is enabled by default when you create a web application using React, Angular, or Vue.js buildpacks. To learn how to set up authentication for your web application with Choreo's managed authentication, see Secure Web Applications with Managed Authentication.

    -
    -
    10. -
  10. -

    Click Create. Choreo initializes the component with the sample implementation and opens the Overview page of the component.

    -
    11. -
-

You have successfully created a Web Application component from the source code. Now let's build and deploy the web application.

-

Build your web application

-

To build the web application, follow the steps given below:

-
    -
  1. In the left navigation menu, click Build.
    2. -
  2. In the Builds pane, click Build. This opens the Commits pane, where you can see all the commits related to the component.
    3. -
  3. -

    Select the latest commit and click Build. This triggers the build process and displays the progress in the Build Logs pane.

    -

    You can access the following scans in the Build Logs pane:

    -
      -
    • The Dockerfile scan: Choreo performs a scan to check if a non-root user ID is assigned to the Docker container to ensure security. If no non-root user is specified, the build will fail.
      • -
    • Container (Trivy) vulnerability scan: This detects vulnerabilities in the final docker image.
      • -
    • Container (Trivy) vulnerability scan: The details of the vulnerabilities open in a separate pane. If this scan detects critical vulnerabilities, the build will fail.
      • -
    -
    -

    Info

    -

    If you have Choreo environments on a private data plane, you can ignore these vulnerabilities and proceed with the deployment.

    -
    -
    -

    Note

    -

    The build process can take a while to complete. When the build process is complete, the build will be listed in the Builds pane along with its status.

    -
    -
    4. -
-

Here, you will see the build status as Success.

-

Deploy and access your web application

-
    -
  1. In the left navigation menu, click Deploy.
    2. -
  2. In the Set Up card, click Configure and Deploy. This opens the Configure & Deploy pane, where you can add a file mount if necessary. In this guide, you will not add a file mount.
    3. -
  3. Click Next. This takes you to the Authentication Settings pane.
    4. -
  4. -

    Keep the default settings and click Deploy.

    -
    -

    Note

    -
      -
    • The deployment process can take a few minutes to complete. On successful deployment, you will see the Deployment Status as Active in the Development card.
      • -
    -
    -
    5. -
  5. -

    To verify that you have successfully hosted the web application, click the Web App URL in the Development card. This takes you to the web application.

    -
    6. -
-

Create a short URL for your web application in production

-
-

Info

-

This feature is only available on the Choreo cloud data plane.

-
-

When you promote your component to the Production environment, you have the option to create a personalized short URL for your web application. The URL follows the https://{your-short-prefix}.choreoapps.dev structure, where you can select a name of your preference for {your-short-prefix}.

-

To create a short URL for your web application, follow the steps given below:

-
    -
  1. Click Promote in the Development card and promote your web application to production.
    2. -
  2. In the Production card, click Create a short URL.
    3. -
  3. -

    Specify a Short URL prefix of your choice and click Save.

    -
    -

    Note

    -

    Short URL names/prefixes are subject to availability, provided on a first-come-first-serve basis.

    -
    -
    4. -
-

Manage runtime configurations for web applications

-

For web applications with a backend server, Choreo allows you to mount runtime configurations and secrets as environment variables and/or file mounts for a specific environment. Alternatively, you can also inject them into the client application during server-side rendering or when serving static content.

-

However, in the case of SPAs that run completely on the browser, Choreo does not support baking-in environment variables or other configurations. This is because Choreo follows a multi-environment deployment model, where configuration should be kept separate from the build and injected at runtime. For example, in most React SPA frameworks, the process.env stub is available during build time. However, it does not actually read in variables from the runtime. Instead, it is baked into the final JavaScript output during the build process.

-

To manage runtime configurations, Choreo recommends the following approach (although this is a React example, the approach is generally applicable to other SPA frameworks as well).

-
-

Note

-
    -
  • With SPAs, anything you mount as a runtime config will be available to your users in the browser.
    • -
  • Do not include sensitive secrets that are not browser-safe.
    • -
-
-

Follow the steps given below to manage runtime configurations for the React application you created above:

-
    -
  1. Go to your forked Choreo samples repository.
    2. -
  2. Open the public directory.
    3. -
  3. -

    Create and commit a new file named config.js in the public directory of your React application. This file should contain the runtime configuration variables you want to expose to your application, such as API endpoints or feature flags. Let's expose the API URL and a feature flag as follows:

    -

    window.config = {
-apiUrl: 'https://api.example.com',
-    featureFlags: {
-        enableNewFeature: true,
-        enableExperimentalFeature: false,
-    },
-};
-
    -4. In your index.html file inside the public directory, add a script tag as follows to include the config.js file inside the tag. The config.js file will be accessible via JavaScript at runtime.

    -

    <!DOCTYPE html>
-<html lang="en">
-<head>
-    <meta charset="utf-8" />
-    <title>My React App</title>
-</head>
-<body>
-    <div id="root"></div>
-    <script src="%PUBLIC_URL%/config.js"></script>
-</body>
-</html>
-
    -This makes the window.config object available to your app at runtime.

    -
    4. -
  4. -

    In your React component, you can access the configuration variables by referencing the window.config object as follows:

    -

    import React from 'react';
-
-function MyComponent() {
-const apiUrl = window.config.apiUrl;
-const enableNewFeature = window.config.featureFlags.enableNewFeature;
-const enableExperimentalFeature = window.config.featureFlags.enableExperimentalFeature;
-
-// ...
-}
-
    -Now you can deploy your component.

    -
    5. -
  5. -

    When you deploy your component to Choreo, create a config file mount in the specified path for each environment (where your index.html expects the config.js file as in this example). -https://wso2.com/choreo/docs/devops-and-ci-cd/manage-configurations-and-secrets/#apply-a-file-mount-to-your-container.

    -
    6. -
-

Limitations

-

The following limitations are specific to the Choreo cloud data plane:

-
    -
  • Request size limit, including headers, cookies, and payloads: 256KB
    • -
  • Response body size limit: 20MB
    • -
  • Only one open port is permitted per web application. While you can have multiple ports open for project-level communication within a data plane, incoming traffic from the internet can only be directed to one port. This differs from the Service type components, which support multiple endpoints.
    • -
-

Troubleshoot a web application

-
    -
  • -

    I’m seeing a blank page or a 502 error after I deploy my web application

    -

    If you encounter a blank page or a 502 error after deploying your web application, it typically indicates that the wrong directory is being served. To resolve this issue, follow these steps:

    -
      -
    • Double-check the build output directory, especially if you are using a Dockerfile-less buildpack. Ensure that the specified output directory matches the actual output directory generated during the build process. For example, if you have erroneously entered public/ as the output directory when it should have been build/.
      • -
    -

    By verifying and correcting the output directory alignment, you should be able to address the issue of encountering a blank page or experiencing a 502 error on deploying your web application.

    -
    • -
- - - - - - -
-
- - -
- - - -
- - -
- - - -
-
-
- - - - - - - - - - - - - - - - - \ No newline at end of file diff --git a/en/site/develop-components/develop-web-applications/develop-web-applications-locally-with-managed-authentication/index.html b/en/site/develop-components/develop-web-applications/develop-web-applications-locally-with-managed-authentication/index.html deleted file mode 100644 index abfca745c..000000000 --- a/en/site/develop-components/develop-web-applications/develop-web-applications-locally-with-managed-authentication/index.html +++ /dev/null @@ -1,3323 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - Develop Web Applications Locally with Choreo’s Managed Authentication - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- - - -
- - - - - - -
- - -
- -
- - - - - - - -
-
- - - -
-
-
- - - - -
-
-
- - - -
-
-
- - - -
-
-
- - - -
-
- - - - - - - - - - - - - - - - - - - - -

Develop Web Applications Locally with Choreo’s Managed Authentication

-

Choreo’s managed authentication capability exposes a set of backend for frontend (BFF) endpoints, facilitating authentication and authorization for web applications. These endpoints are readily available for single-page web applications deployed on Choreo.

-

As a web application developer, there may be instances where it becomes necessary to run the application on your personal workstation. In such situations, the expectation is for authentication and authorization during local development to work in the same manner as it would when the application is deployed to Choreo, eliminating the need to modify the source code.

-

Choreo's local development capability ensures a seamless local application development experience where the authentication and authorization process aligns with Choreo’s deployment environment. This facilitates a smoother transition from development to deployment, improving workflow efficiency.

-

How local development works in Choreo

-

Local development uses a proxy that sits in front of the locally running web application. This proxy intercepts all incoming requests. The requests to /choreo-apis/* and /auth/* are then forwarded to Choreo, while all other requests are forwarded to the locally running web application. The proxy runs on HTTPS using a self-signed certificate, crucial for secure, HTTP-only cookie-based managed authentication. Upon running the proxy, you can access the web application using the proxy's URL and start developing the application locally. You will observe that the behavior of the web application, in terms of the managed authentication functionality, is similar to how it would be after deploying to Choreo.

-

Configure local development

-

Prerequisites

-
    -
  • Create a single-page application (SPA) with managed authentication enabled. For details on how to set up managed authentication for your web application, see Secure Web Applications with Managed Authentication.
    • -
  • -

    Promote and deploy the application to the environment where you want to enable local development.

    -
    -

    Note

    -
      -
    • The web application that you run locally will use the same managed authentication configuration as the environment where you are configuring local development.
      • -
    • Local development is only allowed in non-critical environments.
      • -
    -
    -
    • -
-

Apply configurations

-
    -
  1. Sign in to the Choreo Console.
    2. -
  2. In the Component Listing pane, click on the component you created and deployed by following the prerequisites.
    3. -
  3. In the left navigation menu, click Deploy.
    4. -
  4. Go to the respective environment card depending on the environment where you want to enable local development and click Local Development.
    5. -
  5. In the Local Development pane that opens, click the Local Development toggle to enable it.
    6. -
  6. If you want to update the port on which the local development proxy server runs, click to expand Advanced Configurations and specify a value for Proxy Port.
    7. -
  7. Click Apply.
    8. -
-

Now you have done the necessary configurations to set up local development. The next section walks you through the steps to access your web application so that you can develop it locally.

-

Access your web application to develop it locally

-

Prerequisites

-
    -
  • Ensure that local development is enabled in the environment where you want to proceed with local development.
    • -
  • Ensure that your web application is running locally on http://localhost on a specific port.
    • -
-

Access your web application locally

-

You can either use the Choreo built-in identity provider or external identity provider to access your web application locally.

-
-
-
-
    -
  1. Sign in to the Choreo Console.
    2. -
  2. In the Component Listing pane, click on the component you created and deployed by following the prerequisites.
    3. -
  3. In the left navigation menu, click Deploy.
    4. -
  4. Go to the respective environment card depending on the environment where you want to enable local development and click Local Development.
    5. -
  5. In the Local Development pane that opens, copy the command given under Step 1.
    6. -
  6. Paste the command in a terminal, ensure you replace [APP_PORT] with the port on which your application is running locally, and run the command.
    7. -
  7. -

    To access the application and proceed to develop it, go to the URL given under Step 2 in the Local Development pane.

    -
    -

    Note

    -

    The local development proxy runs on HTTPS using a self-signed certificate. Your browser may warn that the certificate is not valid. Accept the risk and proceed.

    -
    -
    8. -
-
-
-
    -
  1. Sign in to the Choreo Console.
    2. -
  2. In the Component Listing pane, click on the component you created and deployed by following the prerequisites.
    3. -
  3. In the left navigation menu, click Deploy.
    4. -
  4. Go to the respective environment card depending on the environment where you want to enable local development and click Local Development.
    5. -
  5. In the Local Development pane that opens, copy the redirect URLs given under Step 1.
    6. -
  6. Go to the settings in the OAuth application in your identity provider and specify the copied URLs as allowed redirect URLs.
    7. -
  7. Go to the Local Development pane in the Choreo Console and copy the command given under Step 2.
    8. -
  8. Paste the command in a terminal, ensure you replace [APP_PORT] with the port on which your application is running locally, and run the command.
    9. -
  9. -

    To access the application and proceed to develop it, go to the URL given under Step 3 in the Local Development pane.

    -
    -

    Note

    -

    The local development proxy runs on HTTPS using a self-signed certificate. Your browser may warn that the certificate is not valid. Accept the risk and proceed.

    -
    -
    10. -
-
-
-
- - - - - - -
-
- - -
- - - -
- - -
- - - -
-
-
- - - - - - - - - - - - - - - - - \ No newline at end of file diff --git a/en/site/develop-components/manage-deployment-tracks-for-choreo-components/index.html b/en/site/develop-components/manage-deployment-tracks-for-choreo-components/index.html deleted file mode 100644 index 87030b350..000000000 --- a/en/site/develop-components/manage-deployment-tracks-for-choreo-components/index.html +++ /dev/null @@ -1,3326 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - Manage Deployment Tracks for Choreo Components - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- - - -
- - - - - - -
- - -
- -
- - - - - - - -
-
- - - -
-
-
- - - - -
-
-
- - - -
-
-
- - - -
-
-
- - - -
-
- - - - - - - - - - - - - - - - - - - - -

Manage Deployment Tracks for Choreo Components

-

Choreo allows you to create and manage dedicated deployment tracks for components, facilitating independent version control and deployment. This capability also allows you to unlink deployment tracks from associated branches or relink them to different branches so that you can align with your preferred Git workflows, such as the feature branch workflow or GitFlow workflow.

-
-

Info

-

Deployment track creation and management does not apply to API Proxy and BYOI components.

-
-

Create a deployment track

-

Prerequisites:

-
    -
  • Create a component in Choreo.
    • -
-

Follow the steps below to create a deployment track for a component:

-
    -
  1. Sign in to the Choreo Console.
    2. -
  2. In the Component Listing pane, click on the component you want to create a deployment track for.
    3. -
  3. On the header of the component overview page, click the Deployment Track drop-down list.
    4. -
  4. Click + Create New to open the Create Deployment Track dialog.
    5. -
  5. In the Create Deployment Track dialog, do the following:
      -
    1. Select a branch to associate with the deployment track.
      2. -
    2. Optionally, specify a description for the deployment track.
      3. -
    3. To create a deployment track for a service component, specify a unique API version indicating the major and minor version numbers.
      4. -
    -
    6. -
  6. Click Create.
    7. -
- -

If you want to detach a branch reference from a deployment track, you must unlink the branch.

-
-

Info

-

When you unlink the branch of a deployment track, the active deployments are unaffected. However, while you can redeploy the existing deployment, you cannot perform a new deployment.

-
-

Follow the steps below to unlink a deployment track of a component:

-
    -
  1. Sign in to the Choreo Console.
    2. -
  2. In the Component Listing pane, click on the component for which you want to unlink a deployment track.
    3. -
  3. On the header of the component overview page, click the Deployment Track drop-down list and then click View All. This takes you to the component settings page where you can see all the deployment tracks linked to the component.
    4. -
  4. Click the edit icon corresponding to the deployment track you want to unlink.
    5. -
  5. In the Edit Branch dialog that opens, click the Branch Name list and select None.
    6. -
  6. Click Save.
    7. -
- -

To associate a branch reference to an unlinked deployment track, you must link a branch.

-
-

Info

-

To build and deploy the contents of the linked branch, you must perform a manual build and deploy.

-
-

Prerequisites:

-
    -
  • A minimum of two branches in your GitHub repository.
    • -
-

Follow the steps below to link a branch to an unlinked deployment track:

-
    -
  1. Sign in to the Choreo Console.
    2. -
  2. In the Component Listing pane, click on the component you want to associate a branch reference for.
    3. -
  3. On the header of the component overview page, click the Deployment Track drop-down list and then click View All. This takes you to the component settings page where you can see all the deployment tracks linked to the component.
    4. -
  4. Click + Link Branch corresponding to the unlinked deployment track for which you want to associate a branch.
    5. -
  5. In the Link Branch dialog that opens, click the Branch Name list and select the branch you want to relink.
    6. -
  6. Click Save.
    7. -
- -

To switch the branch reference of a linked deployment track, you must relink to an appropriate branch.

-
-

Info

-

If you unlink the existing branch of a deployment track and link a different branch, you must perform a manual build and deploy to build and deploy the contents of the recently linked branch.

-
-

Prerequisites:

-
    -
  • A minimum of two branches in your GitHub repository.
    • -
-

Follow the steps below to switch the branch reference of a linked deployment track:

-
    -
  1. Sign in to the Choreo Console.
    2. -
  2. In the Component Listing pane, click on the component you want to relink a deployment track for.
    3. -
  3. On the header of the component overview page, click the Deployment Track drop-down list and then click View All. This takes you to the component settings page where you can see all the deployment tracks linked to the component.
    4. -
  4. Click the Edit Branch icon corresponding to the deployment track you want to relink.
    5. -
  5. In the Edit Branch dialog that opens, click the Branch Name list and select the branch you want to relink.
    6. -
  6. Click Save.
    7. -
-

Now that you understand how to create and manage deployment tracks for components, let’s explore a sample scenario to see how a developer can use deployment tracks to manage version releases in Choreo.

-

Sample Scenario: Manage version releases with deployment tracks

-

Let’s consider the following version release scenario:

-
    -
  • To initiate work on a new feature, a developer creates a new branch, named feature-x from either the main or dev branch.
    • -
  • Once development is complete, the developer proceeds to merge the feature-x branch into the dev branch for testing.
    • -
  • Upon successful testing in the dev branch, the developer proceeds to merge all the changes into the main branch for production deployment.
    • -
-

Following are the actions you need to take from a deployment track perspective to manage the version release:

-
    -
  1. To prepare for the new version release, unlink the main branch from the associated deployment track (let’s consider this as the deployment track 1).
    2. -
  2. Proceed to merge the dev branch containing the tested changes into the main branch.
    3. -
  3. Unlink the dev branch from the associated deployment track (let’s consider this as deployment track 2).
    4. -
  4. Link deployment track 2 containing the latest version of the service to the main branch for deployment.
    5. -
  5. To facilitate ongoing development and testing, create another deployment track (let’s consider this as deployment track 3) and link it to the dev branch.
    6. -
-
-

Tip

-
    -
  • As a developer, you can strategically unlink and relink deployment tracks to effectively manage different versions of your services within Choreo.
    • -
  • You can create new deployment tracks for ongoing development branches like dev to ensure a continuous development and release cycle.
    • -
-
-

Delete a deployment track

-

If you no longer need a deployment track, you can delete it.

-
-

Note

-

If the component exposes an endpoint or proxy and you want to delete the last version in the major version range, the recommended approach is to retire that version first. This allows consumers to transition to the next major version and prevents a sudden break in their experience. -For example, if you have deployment tracks for v1.0 and v2.0, notify consumers to switch to v2.0 before deleting v1.0. Then, retire the APIs in v1.0 and proceed to delete the associated deployment track.

-
-

Prerequisites:

-
    -
  • At least 2 deployment tracks in a component.
    • -
-

Follow the steps below to delete a deployment track:

-
    -
  1. Sign in to the Choreo Console.
    2. -
  2. In the Component Listing pane, click on the component for which you want to delete a deployment track.
    3. -
  3. On the header of the component overview page, click the Deployment Track drop-down list.
    4. -
  4. Click + View All. This takes you to the component settings page where you can see all the deployment tracks linked to the component.
    5. -
  5. Click the Delete icon corresponding to the deployment track you want to delete.
    6. -
  6. Click Delete to confirm the deletion.
    7. -
- - - - - - -
-
- - -
- - - -
- - -
- - - -
-
-
- - - - - - - - - - - - - - - - - \ No newline at end of file diff --git a/en/site/develop-components/manage-the-micro-integrator-runtime-version-in-your-integration-project/index.html b/en/site/develop-components/manage-the-micro-integrator-runtime-version-in-your-integration-project/index.html deleted file mode 100644 index 8aa9068ac..000000000 --- a/en/site/develop-components/manage-the-micro-integrator-runtime-version-in-your-integration-project/index.html +++ /dev/null @@ -1,3387 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - Manage the Micro Integrator Runtime Version in Your Integration Project - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- - - -
- - - - - - -
- - -
- -
- - - - - - - -
-
- - - -
-
-
- - - - -
-
-
- - - -
-
-
- - - -
-
-
- - - -
-
- - - - - - - - - - - - - - - - - - - - -

Manage the Micro Integrator Runtime Version in Your Integration Project

-

Choreo allows you to use a preferred WSO2 Micro Integrator (MI) runtime version in your integration project. Currently, Choreo supports MI product versions 4.1.0 and 4.2.0. You have the flexibility to deploy WSO2 updates within these specified versions.

-

When you create an integration project, you can specify a required runtime version to gain control over the environment in which your integration runs. This version management capability empowers you to tailor your projects depending on your runtime requirements, enhancing the customization and adaptability of your integration workflows.

-

Understand the version string

-

WSO2 Micro Integrator (MI) utilizes a versioning system consisting of three-digit numbers, such as 4.1.0 and 4.2.0, following semantic versioning principles. The product remains committed to receiving updates from WSO2, including security fixes, bug resolutions, and enhancements. Within the Choreo platform, the MI runtime version is constructed by combining the product release version with its corresponding update level.

-

In Choreo, the MI runtime version is structured as a four-digit number, for example, 4.1.0.14 or 4.2.0.17. The first three digits represent the product release version, while the last digit signifies the update level of the product. The fourth digit is optional and can be omitted.

-

Version string

-

Version management in WSO2 Integration Studio

-

If you are using WSO2 Integration Studio to build and deploy integration artifacts in WSO2 Micro Integrator, you can create multiple runtime environments and execute projects on any selected environment. WSO2 Integration Studio also allows you to configure multiple Micro Integrator runtime environments, offering flexibility and customization in the execution of integration processes.

-

You can specify the Runtime version when you create an integration project in WSO2 Integration Studio. In the project creation wizard, specify the runtime version in the Runtime version field, as shown below. -Specify Runtime version

-

An integration project is structured as a Maven project with multiple sub-modules. The root pom.xml file holds crucial information about the target runtime. The runtime version you configure when you create a new project is saved within the root pom.xml file. The version information is stored in the element under the in the pom.xml file. If there is a need to update the runtime version, you have the flexibility to modify the value to a valid runtime version and ensure that the project runs in the required runtime environment.

-

project runtime version

-

You can establish multiple runtime environments by utilizing updated MI instances. With a valid WSO2 subscription, you can also access and download updates to set up an updated MI server locally. This update process allows you to select a preferred update level as the runtime version. Consequently, you can run your integration on a runtime with the latest updates, ensuring optimal performance and access to new features.

-

Configure a Micro Integrator runtime environment in Integration Studio

-

If you are using WSO2 Integration Studio, follow these steps to set up a remote server instance with a Micro Integrator runtime environment to execute your integration project:

-
-

Note

-

If you have not downloaded and installed WSO2 Integration Studio, you can follow the installation instructions in the WSO2 API Manager documentation.

-
-
    -
  1. Launch WSO2 Integration Studio and click Add Server in the Getting Started view. - Add server
    2. -
  2. In the Define a New Server dialog, click to expand the WSO2 directory and select WSO2 Remote Server. - Define a remote server instance
    3. -
  3. -

    Enter the WSO2 Micro Integrator Management API URL in the Server URL field and click Test Connection.

    -
    -

    Note

    -

    The Management API of WSO2 Micro Integrator is an internal REST API introduced to substitute MI admin services. The default HTTPS port of the Management API of WSO2 Micro Integrator is 9164. If you have not manually changed the default port, you must set the Management API URL as https://localhost:9164/management. If you have changed the default HTTPS port, you must set the port number appropriately when specifying the Server URL. For more information on the default ports of WSO2 Micro Integrator, see WSO2 Micro Integrator default ports in the WSO2 API Manager documentation.

    -
    -

    Set server URL

    -
    4. -
  4. -

    Click Finish.

    -
    5. -
  5. In the Add and Remove dialog, select the integration components to move from the left side to the right side.
    6. -
  6. Click Add >.
    7. -
  7. Click Finish.
    8. -
-

Your integration project is now running in a remote server instance with the Micro Integrator runtime environment you require. -If you need to make changes to the integration project, expand the remote server instance, right-click on the deployed exporter project, and select Redeploy to apply the changes.

-

Redeploy project

-

Convention for version interpretation in Choreo deployments

-

You can use the following convention to indicate the required MI runtime version in your integration project:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Version formatExampleDescription
Product version4.1.0, 4.2.0Deploy on the latest update level of the mentioned product version.
Product version with update level4.1.0.15, 4.2.0.17Deploy on the exact update level of the mentioned product version.
GA version4.1.0.0, 4.2.0.0Deploy on the exact GA version without any update.
Default versionEmpty valueDeploy on the latest update level of the default product version.
-

Choreo utilizes Alpine images for configuring and deploying the Micro Integrator runtime. This includes automated configuration of the JRE/JDK, customized to the compatibility of the chosen runtime version, simplifying the setup procedure.

-

Migrate between runtime versions

-

Changing the runtime version in an integration project may become necessary during product version upgrades or when you want to apply updates.

-

To change the runtime version of a MI Integration, follow the below steps.

-

Update the runtime version in the integration project

-

To change the runtime version in the integration project, follow the steps below: -1. Open the project in Integration Studio. -2. Right-click on the project and select Change Runtime MI Version. - Update Runtime version -3. Specify the new runtime version as shown below: - Update Runtime version -4. Alternatively, you can manually update the version by opening the root pom.xml file. Open pom.xml and change the required runtime version in <project.runtime.version> element under <properties> section.

-

To test the changes locally, you must download and set up the runtime environment locally. Then, you must configure the Integration Studio runtime environment by directing it to the locally installed MI runtime. Once the setup is complete, you can deploy your integrations on the MI runtime environment and proceed to the testing phase.

-

After completing the tests to ensure everything works as expected, you can follow below steps to deploy the project in Choreo:

-
    -
  1. Commit and push the changes to your repository.
    2. -
  2. Go to https://console.choreo.dev/ and sign in.
    3. -
  3. Select your project from the Project list in the header.
    4. -
  4. Select your MI integration component from the Component list in the header.
    5. -
  5. In the left navigation menu, click Build.
    6. -
  6. Select the latest commit and click Build.
    7. -
  7. In the left navigation menu, click Deploy.
    8. -
  8. Click on the Configure and Deploy and deploy the component.
    9. -
  9. Verify the Runtime version by checking the logs by selecting the Runtime Logs under the Observability section.
    10. -
-

You will see the runtime version in the logs as shown below: - Runtime version in logs

-

Next, you must conduct additional testing in the development environment on Choreo before you promote the integration to production environments.

-

Troubleshoot errors

-

The following error codes can help you troubleshoot errors that occur during the integration component build:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Error codeDescription
110 - 119Internal server error.
121Malformed runtime version.
122The specified runtime version is not available. Either the product or update level is not available.
123Trivy security vulnerabilities found in the libs directory.
124Trivy security vulnerabilities found in the dropins directory.
125Trivy security vulnerabilities found in the libs or dropins directory.
126Error building integration project.
- - - - - - -
-
- - -
- - - -
- - -
- - - -
-
-
- - - - - - - - - - - - - - - - - \ No newline at end of file diff --git a/en/site/develop-components/sharing-and-reusing/create-a-connection/index.html b/en/site/develop-components/sharing-and-reusing/create-a-connection/index.html deleted file mode 100644 index caf67f186..000000000 --- a/en/site/develop-components/sharing-and-reusing/create-a-connection/index.html +++ /dev/null @@ -1,3111 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - Create a Connection - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- - - -
- - - - - - -
- - -
- -
- - - - - - - -
-
- - - -
-
-
- - - - -
-
-
- - - -
-
-
- - - -
-
-
- - - -
-
- - - - - - - - - - - - - - - - - - - - -

Create a Connection

-

Connections in Choreo allow you to integrate Choreo components, or to integrate Choreo components to external services or resources. Connections provide a simple and uniform way to integrate with services and resources.

-

To consume a service deployed on Choreo within your service, you must create a connection to the service you want to consume.

-

To create a connection, follow the steps given below:

-
    -
  1. -

    In the Choreo Console, go to the top navigation menu and set the visibility level as project or component as follows:

    -
      -
    • Project Connection: Select an organization and a project in that organization.
      • -
    • Component Connection: Select an organization, a project in that organization, and a component in the selected project.
      • -
    -
    2. -
  2. -

    From the left navigation menu, click Dependencies and then Connections. This page will list the currently available connections.

    -
    3. -
  3. Click +Create. The Create Connection page opens with the marketplace view for you to browse the available services. You can search and apply filters to efficiently find a service.
    4. -
  4. Click on the service you want to connect to.
    5. -
  5. Enter a name and a description for the connection and click Next. This displays the ServiceURL for the development and production environments.
    6. -
  6. Click Finish.
    7. -
-

For step-by-step instructions on how to use a connection in your service, see Use a Connection in Your Service.

-

For step-by-step instructions on how to use a connection in your web application, see Use a Connection in Your Web Application.

- - - - - - -
-
- - -
- - - -
- - -
- - - -
-
-
- - - - - - - - - - - - - - - - - \ No newline at end of file diff --git a/en/site/develop-components/sharing-and-reusing/share-and-reuse-services/index.html b/en/site/develop-components/sharing-and-reusing/share-and-reuse-services/index.html deleted file mode 100644 index 093ae3442..000000000 --- a/en/site/develop-components/sharing-and-reusing/share-and-reuse-services/index.html +++ /dev/null @@ -1,15 +0,0 @@ - - - - - - Redirecting... - - - - - - -Redirecting... - - diff --git a/en/site/develop-components/sharing-and-reusing/share-and-reuse-web-applications/index.html b/en/site/develop-components/sharing-and-reusing/share-and-reuse-web-applications/index.html deleted file mode 100644 index e04a4f385..000000000 --- a/en/site/develop-components/sharing-and-reusing/share-and-reuse-web-applications/index.html +++ /dev/null @@ -1,15 +0,0 @@ - - - - - - Redirecting... - - - - - - -Redirecting... - - diff --git a/en/site/develop-components/sharing-and-reusing/use-a-connection-in-your-service/index.html b/en/site/develop-components/sharing-and-reusing/use-a-connection-in-your-service/index.html deleted file mode 100644 index 59aa743a6..000000000 --- a/en/site/develop-components/sharing-and-reusing/use-a-connection-in-your-service/index.html +++ /dev/null @@ -1,3361 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - Use a Connection in Your Service - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- - - -
- - - - - - -
- - -
- -
- - - - - - - -
-
- - - -
-
-
- - - - -
-
-
- - - -
-
-
- - - -
-
-
- - - -
-
- - - - - - - - - - - - - - - - - - - - -

Use a Connection in Your Service

-

Choreo allows you to share and reuse your services, accelerating development and enhancing efficiency in building integrated applications through connections.

-

For step-by-step on instruction on creating a connection, see Create a Connection.

-

To learn more about Choreo Connections, see the documentation on Connections.

-

Consume a service through a connection

-

You can consume a Choreo-deployed service within another service. Consuming connections from within Choreo services is seamless and straightforward. Follow the steps below to consume a Choreo service:

-

Step 1: Add connection configurations

-

To integrate another service into your application, follow the steps below:

-
    -
  1. -

    Copy and paste the snippet from the in-line developer guide into the component-config file under the spec section.

    -

    The following is a sample snippet:

    -
    outbound:
-    serviceReferences:
-    - name: <SERVICE_NAME>
-      connectionConfig: <CONNECTION_ID>
-      env:
-      - from: ServiceURL
-        to: <YOUR_ENV_VARIABLE_NAME_HERE>
-      - from: ConsumerKey
-        to: <YOUR_ENV_VARIABLE_NAME_HERE>
-      - from: ConsumerSecret
-        to: <YOUR_ENV_VARIABLE_NAME_HERE>
-      - from: TokenURL
-        to: <YOUR_ENV_VARIABLE_NAME_HERE>
-
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    FieldDescription
    NameThe name of the service you are connecting to.
    ConnectionConfigThe unique connection identifier for the connection.
    envThe environment variable mapping.
    fromThe key of the configuration entry.
    toThe environment variable name to which Choreo will inject the value of the key.
    -
    2. -
  2. -

    Replace <YOUR_ENV_VARIABLE_NAME_HERE> with an appropriate environment variable name of your choice. If you have previously added an outbound service reference, append this as another item under serviceReferences.

    -

    Upon deploying the component, Choreo automatically creates a subscription if applicable and populates the specified environment variables with actual values.

    -

    The following table provides details on the configuration keys associated with the connection:

    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    NameTypeDescriptionOptionalSensitive
    ServiceURLstringService URL of the Choreo servicefalsefalse
    ConsumerKeystringConsumer key of the Choreo servicefalsefalse
    ConsumerSecretstringConsumer secret of the Choreo servicefalsetrue
    TokenURLstringToken URL of the STSfalsefalse
    -
    3. -
-

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.

-

The following is a sample code snippet in NodeJS:

-
const serviceURL = process.env.SVC_URL;
-
- -

Step 3: Acquire an OAuth 2.0 access token

-

To consume a Choreo service with the visibility level set to organization or public and secured by the OAuth 2.0 security scheme, you must obtain an OAuth 2.0 token from the token endpoint. Subsequently, you can use the token to invoke the service.

-
    -
  • -

    For languages with OAuth 2.0-aware HTTP clients, you must pass the OAuth 2.0-related configurations such as client id, client secret and so on, obtained when creating the connection to your HTTP client configuration. The HTTP client autonomously manages token retrieval and refreshing.

    -
    • -
  • -

    For languages without OAuth 2.0-aware HTTP clients, you must manually initiate a call to the token endpoint. This includes fetching the token and managing token expiration and refresh directly within your application code. The following is a sample curl command to obtain a token:

    -
    CONSUMER_KEY="your_consumer_key"
-CONSUMER_SECRET="your_consumer_secret"
-TOKEN_URL="your_token_url"
-
-# Encode client credentials as Base64
-CLIENT_CREDENTIALS=$(echo -n "$CLIENT_ID:$CLIENT_SECRET" | base64)
-
-curl -X POST $TOKEN_URL \
-  -H "Content-Type: application/x-www-form-urlencoded" \
-  -H "Authorization: Basic $CLIENT_CREDENTIALS" \
-  --data-urlencode "grant_type=client_credentials"
-
    - -
    • -
-

Step 4: Invoke the Service

-

You can invoke the service as follows:

-
    -
  • -

    For languages with OAuth 2.0-aware HTTP clients, you can invoke the service in a straightforward manner. The HTTP client seamlessly manages OAuth 2.0 authentication without requiring additional intervention.

    -

    As the service URL you can use the URL that you resolved in step 2. For sample requests and responses, see the API definition provided via the Choreo marketplace for the service.

    -
    • -
  • -

    For languages without OAuth 2.0-aware HTTP clients, you can use the token obtained in step 3 to make calls to the dependent service. Subsequently, add the obtained token to the HTTP authorization header with the bearer prefix. -As the service URL you can use the URL that you resolved in step 2. For sample requests and responses, see the API definition of the service provided via the Choreo marketplace.

    -

    The following is a sample code snippet in NodeJS:

    -
    const response = await axios.get(serviceURL/{RESOURCE_PATH}, {
-    headers: {
-      'Authorization': `Bearer ${accessToken}`
-    }
-});
-
    - -
    -

    Note

    -

    If you want to consume a Choreo service at the project visibility level, you don't need to obtain a token. You can directly invoke the service using the resolved URL.

    -
    -
    • -
- - - - - - -
-
- - -
- - - -
- - -
- - - -
-
-
- - - - - - - - - - - - - - - - - \ No newline at end of file diff --git a/en/site/develop-components/sharing-and-reusing/use-a-connection-in-your-web-application/index.html b/en/site/develop-components/sharing-and-reusing/use-a-connection-in-your-web-application/index.html deleted file mode 100644 index f11d88562..000000000 --- a/en/site/develop-components/sharing-and-reusing/use-a-connection-in-your-web-application/index.html +++ /dev/null @@ -1,3217 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - Use a Connection in Your Web Application - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- - - -
- - - - - - -
- - -
- -
- - - - - - - -
-
- - - -
-
-
- - - - -
-
-
- - - -
-
-
- - - -
-
-
- - - -
-
- - - - - - - - - - - - - - - - - - - - -

Use a Connection in Your Web Application

-

Choreo simplifies the process of integrating services into your web application. The approach to connect to a service can vary based on your web application.

-

To connect to a selected service, follow the step-by-step instructions given below depending on the authentication mechanism used in your web application.

-
-
-
-

Choreo-managed authentication allows you to seamlessly handle authentication for your web application. You can configure your web application to work with the built-in identity provider of Choreo or any external identity provider that supports OIDC/OAuth2.0

-
-

Note

-

Choreo's managed authentication is currently available only for web applications created with React, Angular, or Vue.js buildpacks.

-
-

Follow the steps below to use an existing connection within your web application:

-

Step 1: Add the connection configuration

-

To integrate a service into your application, you must first add the connection configuration as follows:

-
    -
  1. -

    For single page applications (SPAs), you must add the connection configuration as a file mount. You can mount a file via the Configurations pane on the Deploy page. You must mount a file (for example, config.js) and add the configuration provided in the in-line developer documentation into it.

    -

    The following is a sample configuration:

    -
         window.configs = {
-         apiUrl: '<SERVICE_URL>',        
-     };
-
    - -
    2. -
  2. -

    To ensure accessibility of the config.js file via JavaScript at runtime, add a script tag as follows in the index.html file to reference the config.js file:

    -
    <!DOCTYPE html>
-<html lang="en">
-<head>
-    <meta charset="utf-8" />
-    <title>My React App</title>
-</head>
-<body>
-    <div id="root"></div>
-    <script src="%PUBLIC_URL%/config.js"></script>
-</body>
-</html>
-
    - -
    -

    Note

    -

    If you use an external IdP, you must add the IdP's configuration to the same file.

    -

    For more information on working with IdPs, see Configure Asgardeo as an External Identity Provider.

    -
    -
    3. -
-

Step 2: Read the configuration

-

Once you add the connection configuration, you can proceed to read the configuration from your application. The steps to read depend on the programming language you use.

-

The following is a sample code snippet in NodeJS:

-
     const serviceURL = window?.configs?.apiUrl ? window.configs.apiUrl : "/";
-
- -

Step 3: Invoke the service

-

If you use Choreo-managed authentication, Choreo handles the security handshaking for the application during deployment. The connected service will be accessible under the same domain as your application. Therefore, you can call the configured path directly using your preferred HTTP client.

-

The following is a sample code snippet in NodeJS:

-
     const response = await axios.get(serviceURL/{RESOURCE_PATH});
-
- -
-

Note

-

If you are using an external IdP provider instead of Choreo-managed authentication, you must obtain an access token from your IdP and add it to the HTTP authorization header with the bearer prefix.

-
-
-
-

If you are not using Choreo-managed authentication or your web application lacks authentication, follow the steps below to connect to a service from your web application:

-

Step 1: Add the connection configuration

-

For single-page applications (SPAs), you must add the connection configuration as a file mount. You can mount a file via the Configurations pane on the Deploy page. You must mount a file (for example, config.js) and add the following configuration into it.

-

The following is a sample configuration:

-
     window.configs = {
-         apiUrl: '<SERVICE_URL>',
-         consumerKey: '<CONSUMER_KEY>',
-         consumerSecret: '<CONSUMER_SECRET>',
-         tokenUrl: '<TOKEN_URL>',
-     };
-
- -

For other types of web applications, you must add the respective configuration into your application.

-

Step 2: Read the configuration

-

Once you have added the connection configuration, you can proceed to read the configuration from your application. The steps to read depend on the programming language you use.

-

The following is a sample code snippet in NodeJS:

-
     const serviceURL = window?.configs?.apiUrl ? window.configs.apiUrl : "/";
-
- -

Step 3: Acquire an OAuth 2.0 access token

-
    -
  • -

    For languages with OAuth 2.0-aware HTTP clients, you must pass the OAuth 2.0-related configurations such as client id, client secret and so on, obtained when creating the connection to your HTTP client configuration. The HTTP client autonomously manages token retrieval and refreshing.

    -
    • -
  • -

    For languages without OAuth 2.0-aware HTTP clients, you must manually initiate a call to the token endpoint. This includes fetching the token and managing token expiration and refresh directly within your application code. The following is a sample curl command to obtain a token:

    -
    CONSUMER_KEY="your_consumer_key"
-CONSUMER_SECRET="your_consumer_secret"
-TOKEN_URL="your_token_url"
-
-# Encode client credentials as Base64
-CLIENT_CREDENTIALS=$(echo -n "$CLIENT_ID:$CLIENT_SECRET" | base64)
-
-curl -X POST $TOKEN_URL \
--H "Content-Type: application/x-www-form-urlencoded" \
--H "Authorization: Basic $CLIENT_CREDENTIALS" \
---data-urlencode "grant_type=client_credentials"
-
    - -
    • -
-

Step 4: Invoke the service

-

You can invoke the service as follows:

-
    -
  • -

    For languages with OAuth 2.0-aware HTTP clients, you can invoke the service in a straightforward manner. The HTTP client seamlessly manages OAuth 2.0 authentication without requiring additional intervention.

    -

    As the service URL you can use the URL that you resolved in step 2 above. For sample requests and responses, see the API definition provided via the Choreo marketplace for the service.

    -
    • -
  • -

    For languages without OAuth 2.0-aware HTTP clients, you can use the token obtained in step 3 above to make calls to the dependent service. Subsequently, add the obtained token to the HTTP authorization header with the bearer prefix.

    -

    As the service URL you can use the URL that you resolved in step 2 above. For sample requests and responses, see the API definition of the service provided via the Choreo marketplace.

    -

    The following is a sample code snippet in NodeJS:

    -
        const response = await axios.get(serviceURL/{RESOURCE_PATH}, {
-        headers: {
-        'Authorization': `Bearer ${accessToken}`
-        }
-    })
-
    - -
    • -
-
-
-
- - - - - - -
-
- - -
- - - -
- - -
- - - -
-
-
- - - - - - - - - - - - - - - - - \ No newline at end of file diff --git a/en/site/develop-components/work-with-the-micro-integrator-runtime-in-choreo/index.html b/en/site/develop-components/work-with-the-micro-integrator-runtime-in-choreo/index.html deleted file mode 100644 index 3823d9a4b..000000000 --- a/en/site/develop-components/work-with-the-micro-integrator-runtime-in-choreo/index.html +++ /dev/null @@ -1,3618 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - Get Started with the Micro Integrator Runtime - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- - - -
- - - - - - -
- - -
- -
- - - - - - - -
-
- - - -
-
-
- - - - -
-
-
- - - -
-
-
- - - -
-
-
- - - -
-
- - - - - - - - - - - - - - - - - - - - -

Work with the Micro Integrator Runtime in Choreo

-

WSO2 Micro Integrator (WSO2 MI) is a lightweight, high-performance integration runtime. It allows you to run integrations developed using WSO2 Integration Studio within Choreo.

-

The topics on this page walk you through the key aspects you need to understand to use the WSO2 MI runtime effectively in Choreo.

-

Integration types

-

Choreo supports the following WSO2 MI integrations that cater to different use cases and requirements. Each integration type serves a specific purpose. Therefore, it is essential to understand their differences to easily choose the most appropriate integration for your use case.

-
    -
  • Service: Exposes an integration as an API via HTTP, making it possible to create a RESTful interface for your integration services. This type is ideal for scenarios where you need to provide an API for external systems or clients to interact with your integration.
    • -
  • Event Handler: Triggers an integration based on external events such as messages arriving on a queue or updates in a database. This type is well-suited for implementing event-driven architectures or responding to changes in your system's environment.
    • -
  • Scheduled Task: Runs an integration automatically at predefined time intervals, ensuring that specific integration tasks occur at regular intervals. This type is ideal for batch processing, data synchronization, or periodic maintenance tasks.
    • -
  • Manual Task: Initiates an integration via user action, giving you full control over when the integration executes. This type is useful for on-demand tasks, testing, or debugging purposes.
    • -
-

Develop integrations with WSO2 Integration Studio

-

WSO2 Integration Studio is a powerful, Eclipse-based graphical development environment that enables you to build and deploy integration artifacts in WSO2 Micro Integrator. This comprehensive IDE offers a robust set of tools for designing and testing integration flows and crafting integration artifacts. By utilizing the visual, drag-and-drop capabilities of WSO2 Integration Studio, developers can significantly reduce the time and effort needed to construct and deploy integration flows.

-

In addition to streamlining the development process, Integration Studio offers features such as debugging, testing, and version control to ensure the quality and reliability of integration flows. By creating an Integration project and Composite Exporter project in WSO2 Integration Studio, developers can export their integration projects as a single deployment artifact, known as a composite application. This composite application encompasses all the components and configurations necessary for deploying the integration project to WSO2 Micro Integrator.

-

The Composite Exporter project simplifies the deployment process by allowing developers to package their integration projects as a single, self-contained artifact that can be easily deployed and managed. This approach enhances the consistency and reliability of integration projects while streamlining the overall deployment process.

-

To start developing integrations with WSO2 Integration Studio, see WSO2 API Manager Documentation - Developing Integration Solutions.

-

Integration project directory structure

-

An Integration Project in WSO2 Integration Studio is a multi-module Maven project that can contain multiple modules with WSO2 Synapse configurations and a composite application module to export all the configurations as a single deployable artifact.

-

An integration project directory structure includes the following key components:

-
    -
  • WSO2 Synapse configurations: These modules contain the essential configurations for the integration project.
    • -
  • Composite Application module: This module is responsible for exporting all the Synapse configurations as a single deployable artifact.
    • -
-

Optionally, you can include the following components in your integration project:

-
    -
  • OpenAPI definition file: You can add the OpenAPI definition file to any location within the project. When creating a component, you'll need to define the path to this file. Choreo will automatically generate an OpenAPI definition for you based on your integration project, if you don't provide one.
    • -
  • Java libraries: If your integration project requires additional Java libraries, you can add them to the libs directory located in the project root.
    • -
  • deployment.toml file: This optional configuration file allows you to customize the preconfigured settings of WSO2 MI instances running on Choreo. By including this file, you can tailor the behavior of your WSO2 MI instances to better suit your project's specific requirements.
    • -
-

Understanding the Integration Project directory structure is crucial for organizing your project and ensuring that all necessary components are included in the final deployable artifact.

-

OpenAPI support

-

OpenAPI Support plays a crucial role in enhancing the functionality of integrations exposed as APIs. By providing an OpenAPI definition for your exposed integration, you can streamline testing and management processes, ensuring a more efficient and user-friendly experience. Choreo will automatically generate an OpenAPI definition for you based on your integration project, if you don't provide one, saving you time and effort.

-

To incorporate OpenAPI support, store the OpenAPI definition file within the repository hosting your Integration Studio project. When creating the project, simply point to the file's location in the repository. If needed, you can change the location of the OpenAPI definition file later via the deploy page.

-

Open API file

-

By leveraging OpenAPI Support, you can optimize the way you test and manage your integrations, resulting in a more efficient development process and a smoother user experience.

-

Work with third-party libraries

-

The use of third-party libraries in your Micro Integrator project can offer several advantages, such as enhanced functionality, improved integration capabilities, optimized performance, and reduced development time.

-

Here are some of the benefits of adding third-party JARs to the Micro Integrator:

-
    -
  • Increased functionality: Third-party libraries can extend the core Micro Integrator distribution, allowing for greater flexibility and customization of integration solutions.
    • -
  • Enhanced integration capabilities: Third-party libraries enable the Micro Integrator to interact with existing systems such as databases or other APIs, improving overall integration capabilities.
    • -
  • Optimized performance: By offering optimized implementations of common functions, third-party libraries can improve the performance of the Micro Integrator.
    • -
  • Efficient development: Developers can avoid re-implementing commonly used functions, reducing development time and increasing efficiency.
    • -
-

To incorporate third-party libraries into your Micro Integrator project, create a new directory called libs at the -root of your project. If your project root and GitHub repository root are not the same, place the libs directory in -the project root. After adding the required JAR files to the libs directory, the Micro Integrator runtime will -automatically include them when deploying the component. This process ensures that any dependencies needed by your -integration flow are available at runtime.

-

In addition to jar libraries, you may also need to incorporate OSGi bundle JARs into your project. To do this, -create another directory called dropins at the root of your project. Similarly, if the project root and GitHub -repository root differ, place the dropins directory in the project root. Within the dropins directory, add the OSGi -bundle JAR files. The OSGI runtime will pick up these bundles during deployment, enabling you to utilize their -functionality within your Micro Integrator project.

-

Libs directory

-

Importing custom certificates to MI

-

The feature enables Choreo MI users to import certificates into the MI client-truststore.jks file. This functionality -proves valuable when users need to establish connections with servers or services utilizing SSL/TLS encryption and -possessing self-signed certificates or certificates issued by private certificate authorities (CAs) that are not -automatically trusted. Importing the certificate to the MI client-truststore.jks file enables MI clients to establish secure connections with -the server or service seamlessly, eliminating SSL/TLS errors or warnings.

-

Before importing the certificate, it is necessary to obtain the certificate file, which can be in PEM or DER format. You -can get the certificate from the server or service provider or export it from a web browser. Certificates should be -added to the /wso2mi/certs/ folder. Users need to verify that the mount path for the certificate file aligns with this -specific path.

-
    -
  1. In the Choreo console, select the component you wish to add a certificate to.
    2. -
  2. From the left navigation click Deploy.
    3. -
  3. Click on the Configs and Secrets tab.
    4. -
  4. Click Create.
    5. -
  5. Select ConfigMap as the Config Type and File Mount as the Mount Type.
    6. -
  6. Click Next.
    7. -
  7. -

    Specify the following values as mount configurations:

    - - - - - - - - - - - - - - - - - -
    FieldValue
    Config NameAn appropriate name for the certificate.
    Mount path/wso2mi/certs/<filename>. For example, /wso2mi/certs/certificate.crt
    -
    8. -
  8. -

    Click Upload File and attach the certificate.

    -
    9. -
  9. Click Create.
    10. -
-

Working with sensitive data using MI Secure Vault

-

MI Secure Vault is a feature that allows users to securely store sensitive data, such as passwords and tokens, and -provide access to that data to MI Integrations. This feature provides an added layer of security to your integrations by -reducing the risk of accidental exposure of sensitive data.

-

To use MI Secure Vault to work with sensitive data, follow these steps:

-
    -
  1. Select the component from the Choreo Console.
    2. -
  2. From the left navigation, click Deploy.
    3. -
  3. Click on the Configure and Deploy.
    4. -
  4. Click on the Add Environment Configurations
    5. -
  5. -

    Specify the following values as configurations:

    - - - - - - - - - - - - - - - - - -
    FieldValue
    NameAn appropriate name for the secret/alias.
    ValueValue for the secret
    -
    6. -
  6. -

    Select Mark as a Secret.

    -
    7. -
  7. Click Add.
    8. -
  8. Click Deploy.
    9. -
  9. Once the secret has been created, you can access it in your integration code using the following syntax:
    10. -
-

<property name="secret_value_1" expression="wso2:vault-lookup('user_pass')" scope="default" type="STRING"/>
-
-This code retrieves the secret named "user_pass" from the MI Secure Vault and stores it in the property named " -secret_value_1". You can then use this property in your integration code to access the secret value.

-

You can refer to the Accessing secrets -section of MI Secure Vault documentation for more information on these features. By using MI -Secure Vault to store and access sensitive data in your integrations, you can ensure that your integrations -remain secure and protect sensitive data from unauthorized access.

-

Scan third-party libraries to identify security vulnerabilities

-

Scanning third-party libraries for security vulnerabilities is essential for identifying potential weaknesses in an application that could be exploited by attackers. Taking a proactive approach to security helps organizations detect and mitigate risks before they can be exploited, preventing data breaches, system compromises, and other security incidents.

-

Choreo incorporates a security vulnerability scanning process during deployment. It uses Trivy to scan and detect critical vulnerabilities in third-party libraries added to the integration component. If the scan uncovers any critical vulnerabilities, the deployment process is halted. The deployment pane displays the Trivy scan status and any security failures in the Library (Trivy) vulnerable scan step, which can be accessed by clicking on it. Once the vulnerability has been addressed, you can redeploy the component.

-

Customize WSO2 Micro Integrator preconfigured settings

-

Customizing WSO2 Micro Integrator Preconfigured Settings is essential for ensuring that the integration solution works optimally within the specific context of your organization. While WSO2 MI comes with preconfigured settings designed for general use, these settings may not be suitable for every organization's unique requirements. Customizing these settings can help optimize performance and ensure compatibility with your organization's systems and applications.

-

To customize the preconfigured settings of WSO2 MI instances running on Choreo, define a deployment.toml file in the GitHub repository subpath of your Micro Integrator project:

-

deployment.toml

-
-

Note

-

If you change critical configuration parameters such as port offset and hostname, it can break internal communication. -Therefore, the recommended approach is to update only the necessary configuration parameters.

-
-

Given below is a sample deployment.toml file that can be used to configure the JMS transport. For more information on WSO2 MI -configuration parameters, see the MI Config Catalog.

-
[[transport.jms.sender]]
-name = "myQueueSender"
-parameter.initial_naming_factory = "org.apache.activemq.jndi.ActiveMQInitialContextFactory"
-parameter.provider_url = "$env{JMS_PROVIDER_URL}"
-parameter.connection_factory_name = "QueueConnectionFactory"
-parameter.connection_factory_type = "queue"
-parameter.cache_level = "producer"
-
-[[transport.jms.listener]]
-name = "myQueueListener"
-parameter.initial_naming_factory = "org.apache.activemq.jndi.ActiveMQInitialContextFactory"
-parameter.provider_url = "$env{JMS_PROVIDER_URL}"
-parameter.connection_factory_name = "QueueConnectionFactory"
-parameter.connection_factory_type = "queue"
-parameter.cache_level = "consumer"
-
- -

Environment variables

-

Using environment variables is a recommended practice when developing integration artifacts with WSO2 Integration Studio, as it improves configuration management, security, portability, and manageability. By leveraging environment variables, organizations can streamline the management and maintenance of their integrations, ensuring that updates can be implemented quickly and efficiently.

-

The component's Deploy page provides a user-friendly interface to manage environment variables across different environments. For information on managing environment variables for complex use cases, see Configurations and secrets.

-

Environment variables

-

Environment variables offer several benefits:

-
    -
  • Configuration management: They simplify the process of managing and updating configuration settings, making it easier to maintain consistency across different environments.
    • -
  • Security: Environment variables help protect sensitive information by storing it securely and separating it from the main codebase.
    • -
  • Portability: By using environment variables, you can ensure that your integration artifacts can be easily migrated and deployed across various environments with minimal changes.
    • -
  • Manageability: Environment variables offer a centralized way to manage configuration settings, making it easier to update and maintain your integrations over time.
    • -
-

For a comprehensive list of parameters that can be configured as environment variables, see WSO2 API Manager Documentation - Injecting Parameters - Supported parameters.

-

Configure logging

-

Configuring logging is crucial when developing and maintaining a software system, as it can significantly improve efficiency during the development, testing, and maintenance phases of the software development process. Logging captures events and messages that occur during an application's execution, providing valuable insights for troubleshooting and debugging issues.

-

With Micro Integrator instances, you can configure and customize logging according to your requirements. Logging configurations can be added to each MI instance's environment, allowing you to fine-tune logging depending on the specific environment or deployment scenario.

-

To configure logging in MI instances, follow the steps given below:

-
-

Tip

-

You can use environment variables with specific naming conventions.

-
-
    -
  1. Start the variable name with logging_level_ followed by the package or class name.
    2. -
  2. Replace the dot character in the package name with an underscore.
    3. -
  3. -

    Set the variable value to the required logging level for the corresponding package or class.

    -

    For example, to enable wire logs, change the logging level of the org.apache.synapse.transport.http.wire package to debug.

    -
    4. -
-

To configure logging, set the environment variable as follows:

-
    -
  1. In the left navigation menu, click Deploy and then click Configs & Secrets.
    2. -
  2. Click + Create.
    3. -
  3. Select ConfigMap as the Config Type and Environment Variables as the Mount Type.
    4. -
  4. Click Next.
    5. -
  5. -

    Specify the following values as mount configurations:

    - - - - - - - - - - - - - - - - - - - - - -
    FieldValue
    Config NameAn appropriate name for the configuration.
    Namelogging_level_org_apache_synapse_transport_http_wire
    Valuedebug
    -
    6. -
  6. -

    Click Create.

    -
    7. -
-

Connectors

-

WSO2 Micro Integrator (MI) Connectors are prebuilt connectors designed to simplify integration between WSO2 MI and various other systems. They enable seamless connections to databases, message brokers, REST APIs, and more, allowing you to perform actions such as sending messages, executing queries, or retrieving data. These connectors are easy to use, making it straightforward to incorporate them into your WSO2 MI integration flows. Micro Integrator connectors are versatile and can be utilized in various integration scenarios, including data integration, service-oriented architecture (SOA) integration, and event-driven architecture (EDA) integration.

-

WSO2 Integration Studio is a comprehensive development environment that facilitates the creation of integration flows using WSO2 Micro Integrator Connectors. With Integration Studio, you can design and implement integration flows that connect diverse systems and execute various actions, such as sending messages, executing queries, or retrieving data. You can build integration flows using either prebuilt connectors provided by WSO2 MI or custom connectors developed using the Connector Development Toolkit. Integration Studio offers a graphical user interface that simplifies the process of building and testing integration flows while also providing a set of tools for managing and deploying these flows in a WSO2 MI runtime environment.

-

For more information, see the following topics in the WSO2 API Manager documentation.

- -

Deploying integrations in Choreo

-

WSO2 MI buildpack is where you can deploy integrations developed with WSO2 Micro Integrator as an API. In this preset, you have three different ways to define endpoints. Choreo gives priory to the definition of endpoints in the below-mentioned order.

-
    -
  1. -

    Using endpoints.yaml file -This is the most flexible method to define endpoints. You can configure the endpoint details with the endpoints.yaml configuration file. Place this file in the .choreo directory in the project path of the component. -If the Micro Integrator project has inbound endpoints, you can expose them via different endpoints using the endpoints.yaml

    -

    See Understanding the endpoints.yaml file to learn about the endpoints.yaml file.

    -
    2. -
  2. -

    Auto generating endpoints -If endpoints.yaml is not provided and if the source Micro Integrator project has APIs, Choreo scans the project and generates the API endpoints. If the project has few APIs, an endpoint will be generated for each API. The visibility of this auto-generated endpoint is set to Public by default. You can change the visibility in the deployment flow.

    -
    3. -
  3. -

    Provide default endpoints -If endpoints.yaml is not provided and if the source Micro Integrator project doesn't have APIs, Choreo generates a default endpoint which will expose the default micro integrator port (8290) with Public visibility and wildcard context.

    -
    4. -
-

Explore Choreo examples on GitHub

-

For a hands-on experience with MI-based integrations in Choreo, we recommend exploring our samples in Choreo Console. You can filter out the samples based on the buildpack WSO2 MI. This will point you to the samples in the Choreo samples GitHub repository

-

Choreo samples - GitHub Repository

-
    -
  • -

    Fork the Repository: Start by forking the repository to your account.

    -
    • -
  • -

    Explore & run: Navigate through the different integration scenarios. Each example has a README.md with setup and execution instructions.

    -
    • -
- - - - - - -
-
- - -
- - - -
- - -
- - - -
-
-
- - - - - - - - - - - - - - - - - \ No newline at end of file diff --git a/en/site/develop-integrations/develop-a-scheduled-integration/index.html b/en/site/develop-integrations/develop-a-scheduled-integration/index.html deleted file mode 100644 index 9aca84db2..000000000 --- a/en/site/develop-integrations/develop-a-scheduled-integration/index.html +++ /dev/null @@ -1,15 +0,0 @@ - - - - - - Redirecting... - - - - - - -Redirecting... - - diff --git a/en/site/develop-integrations/develop-an-event-triggered-integration/index.html b/en/site/develop-integrations/develop-an-event-triggered-integration/index.html deleted file mode 100644 index 8118f0933..000000000 --- a/en/site/develop-integrations/develop-an-event-triggered-integration/index.html +++ /dev/null @@ -1,15 +0,0 @@ - - - - - - Redirecting... - - - - - - -Redirecting... - - diff --git a/en/site/develop/api-policies/attach-policies/index.html b/en/site/develop/api-policies/attach-policies/index.html deleted file mode 100644 index 40f377644..000000000 --- a/en/site/develop/api-policies/attach-policies/index.html +++ /dev/null @@ -1,15 +0,0 @@ - - - - - - Redirecting... - - - - - - -Redirecting... - - diff --git a/en/site/develop/api-policies/create-a-policy/index.html b/en/site/develop/api-policies/create-a-policy/index.html deleted file mode 100644 index 40f377644..000000000 --- a/en/site/develop/api-policies/create-a-policy/index.html +++ /dev/null @@ -1,15 +0,0 @@ - - - - - - Redirecting... - - - - - - -Redirecting... - - diff --git a/en/site/develop/api-policies/policies/index.html b/en/site/develop/api-policies/policies/index.html deleted file mode 100644 index 40f377644..000000000 --- a/en/site/develop/api-policies/policies/index.html +++ /dev/null @@ -1,15 +0,0 @@ - - - - - - Redirecting... - - - - - - -Redirecting... - - diff --git a/en/site/develop/components/api-proxies/policies/index.html b/en/site/develop/components/api-proxies/policies/index.html deleted file mode 100644 index ab7382632..000000000 --- a/en/site/develop/components/api-proxies/policies/index.html +++ /dev/null @@ -1,15 +0,0 @@ - - - - - - Redirecting... - - - - - - -Redirecting... - - diff --git a/en/site/develop/components/api-proxy/index.html b/en/site/develop/components/api-proxy/index.html deleted file mode 100644 index b6c31b837..000000000 --- a/en/site/develop/components/api-proxy/index.html +++ /dev/null @@ -1,15 +0,0 @@ - - - - - - Redirecting... - - - - - - -Redirecting... - - diff --git a/en/site/develop/components/graphql-api/index.html b/en/site/develop/components/graphql-api/index.html deleted file mode 100644 index 6687d8ac7..000000000 --- a/en/site/develop/components/graphql-api/index.html +++ /dev/null @@ -1,15 +0,0 @@ - - - - - - Redirecting... - - - - - - -Redirecting... - - diff --git a/en/site/develop/components/manual-trigger/index.html b/en/site/develop/components/manual-trigger/index.html deleted file mode 100644 index 01f424356..000000000 --- a/en/site/develop/components/manual-trigger/index.html +++ /dev/null @@ -1,15 +0,0 @@ - - - - - - Redirecting... - - - - - - -Redirecting... - - diff --git a/en/site/develop/components/rest-api/index.html b/en/site/develop/components/rest-api/index.html deleted file mode 100644 index 3ae58b707..000000000 --- a/en/site/develop/components/rest-api/index.html +++ /dev/null @@ -1,15 +0,0 @@ - - - - - - Redirecting... - - - - - - -Redirecting... - - diff --git a/en/site/develop/components/scheduled-trigger/index.html b/en/site/develop/components/scheduled-trigger/index.html deleted file mode 100644 index ee4d4f84e..000000000 --- a/en/site/develop/components/scheduled-trigger/index.html +++ /dev/null @@ -1,15 +0,0 @@ - - - - - - Redirecting... - - - - - - -Redirecting... - - diff --git a/en/site/develop/components/service/index.html b/en/site/develop/components/service/index.html deleted file mode 100644 index d832de08e..000000000 --- a/en/site/develop/components/service/index.html +++ /dev/null @@ -1,15 +0,0 @@ - - - - - - Redirecting... - - - - - - -Redirecting... - - diff --git a/en/site/develop/components/webhook/index.html b/en/site/develop/components/webhook/index.html deleted file mode 100644 index 8cddf1c85..000000000 --- a/en/site/develop/components/webhook/index.html +++ /dev/null @@ -1,15 +0,0 @@ - - - - - - Redirecting... - - - - - - -Redirecting... - - diff --git a/en/site/develop/manage-repository/connect-your-own-github-repository-to-choreo/index.html b/en/site/develop/manage-repository/connect-your-own-github-repository-to-choreo/index.html deleted file mode 100644 index 67d4dfb3b..000000000 --- a/en/site/develop/manage-repository/connect-your-own-github-repository-to-choreo/index.html +++ /dev/null @@ -1,15 +0,0 @@ - - - - - - Redirecting... - - - - - - -Redirecting... - - diff --git a/en/site/develop/run-and-test/forecast-performance-metrics/index.html b/en/site/develop/run-and-test/forecast-performance-metrics/index.html deleted file mode 100644 index 01f424356..000000000 --- a/en/site/develop/run-and-test/forecast-performance-metrics/index.html +++ /dev/null @@ -1,15 +0,0 @@ - - - - - - Redirecting... - - - - - - -Redirecting... - - diff --git a/en/site/developer-portal/developer-portal/index.html b/en/site/developer-portal/developer-portal/index.html deleted file mode 100644 index be2480499..000000000 --- a/en/site/developer-portal/developer-portal/index.html +++ /dev/null @@ -1,15 +0,0 @@ - - - - - - Redirecting... - - - - - - -Redirecting... - - diff --git a/en/site/developer-portal/manage-application/index.html b/en/site/developer-portal/manage-application/index.html deleted file mode 100644 index ba29e0924..000000000 --- a/en/site/developer-portal/manage-application/index.html +++ /dev/null @@ -1,15 +0,0 @@ - - - - - - Redirecting... - - - - - - -Redirecting... - - diff --git a/en/site/developer-portal/manage-subscription/index.html b/en/site/developer-portal/manage-subscription/index.html deleted file mode 100644 index 2ca5a5090..000000000 --- a/en/site/developer-portal/manage-subscription/index.html +++ /dev/null @@ -1,15 +0,0 @@ - - - - - - Redirecting... - - - - - - -Redirecting... - - diff --git a/en/site/developer-portal/test-api/index.html b/en/site/developer-portal/test-api/index.html deleted file mode 100644 index ad391b29d..000000000 --- a/en/site/developer-portal/test-api/index.html +++ /dev/null @@ -1,15 +0,0 @@ - - - - - - Redirecting... - - - - - - -Redirecting... - - diff --git a/en/site/devops-and-ci-cd/autoscale-component-replicas/index.html b/en/site/devops-and-ci-cd/autoscale-component-replicas/index.html deleted file mode 100644 index f9cda5494..000000000 --- a/en/site/devops-and-ci-cd/autoscale-component-replicas/index.html +++ /dev/null @@ -1,15 +0,0 @@ - - - - - - Redirecting... - - - - - - -Redirecting... - - diff --git a/en/site/devops-and-ci-cd/autoscale/autoscale-component-replicas/index.html b/en/site/devops-and-ci-cd/autoscale/autoscale-component-replicas/index.html deleted file mode 100644 index 89383a7f1..000000000 --- a/en/site/devops-and-ci-cd/autoscale/autoscale-component-replicas/index.html +++ /dev/null @@ -1,3119 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - Autoscale Component Replicas - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- - - -
- - - - - - -
- - -
- -
- - - - - - - -
-
- - - -
-
-
- - - - -
-
-
- - - -
-
-
- - - -
-
-
- - - -
-
- - - - - - - - - - - - - - - - - - - - -

Autoscale Component Replicas

-

Choreo allows you to automatically scale your component replicas up or down in number based on resource consumption to ensure high availability.

-
-

Note

-

Autoscaling capabilities are only available in paid plans for private data plane organizations. -In the free tier, components run in a single-replica, low-availability mode.

-
-

Scale component replicas

-

The following parameters allow you to scale component replicas:

-
    -
  • Min replicas: The minimum number of replicas to run at any given time. It is recommended to keep the value at a minimum of 2.
    • -
  • Max replicas: The maximum number of replicas to scale up to. In the cloud data plane, this is restricted to a maximum of 5. There is no restriction on the value in private data planes.
    • -
  • CPU Threshold: The average CPU utilization across all running replicas. If the CPU utilization across all active instances reaches the threshold, the number of active replicas automatically scales up until the average CPU utilization falls below the threshold.
    • -
  • Memory Threshold: The average memory usage across all running replicas. Like the CPU Threshold, if all active instances reach the memory threshold, the number of active replicas automatically scales up until the average memory usage falls below the threshold.
    • -
-
-

Tip

-

If you update a scaling parameter, it may not immediately reflect in the Choreo Console because the change can take some time to propagate.

-
-
-

Run a fixed number of replicas

-

If you want to run exactly 3 replicas for a component, you must set the minimum and maximum replicas to 3.

-
-
-

Scale to zero

-
    -
  • Although it is possible to set the minimum number of replicas to 0, your component does not scale to zero automatically during low usage. It can only go down to 1 replica.
    • -
  • Setting both the minimum and maximum replicas to 0 suspends the deployment.
    • -
-
- - - - - - -
-
- - -
- - - -
- - -
- - - -
-
-
- - - - - - - - - - - - - - - - - \ No newline at end of file diff --git a/en/site/devops-and-ci-cd/autoscale/autoscale-components-with-scale-to-zero/index.html b/en/site/devops-and-ci-cd/autoscale/autoscale-components-with-scale-to-zero/index.html deleted file mode 100644 index 42397db94..000000000 --- a/en/site/devops-and-ci-cd/autoscale/autoscale-components-with-scale-to-zero/index.html +++ /dev/null @@ -1,3257 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - Autoscale Components with Scale-to-Zero - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- - - -
- - - - - - -
- - -
- -
- - - - - - - -
-
- - - -
-
-
- - - - -
-
-
- - - -
-
-
- - - -
-
-
- - - -
-
- - - - - - - - - - - - - - - - - - - - -

Autoscale Components with Scale-to-Zero

-

Choreo provides the scale-to-zero capability for HTTP applications you deploy in the data plane. This lets you run your components in a serverless mode.

-

Scale to zero is very useful in lower environments, where you can significantly reduce infrastructure costs by scaling down idle workloads. In production environments, you can also use scale-to-zero capability if your application's behavior aligns with this feature behavior. In the paid tier, if you want to run your application with more guaranteed high availability, it is recommended to choose HPA (Horizontal Pod Autoscaler) scaling method and configure a minimum replica count of 2 or higher.

-

How Scale to Zero works in Choreo

-
-

Info

-

For service components and web-apps you create after February 23, 2024, Choreo enables the scale-to-zero feature by default.

-
-

When Scale to Zero is enabled, your apps will automatically scale down to zero unless they receive HTTP traffic. When the application receives an HTTP request, your workload quickly scales up from zero to handle the request. When a new request is received by the deployment, the deployment will scale up to one replica and serve the request. When the deployment remains idle for a set period (approximately 5 minutes), it will automatically scale back to zero until a new request is received.

-

When Scale to Zero is enabled, you can set the maximum number of replicas for deployments with this capability. Choreo dynamically scales deployments up to meet high HTTP traffic demand, up to the specified number of replicas. If the pending requests surpass the defined threshold under Number of pending requests to spawn a new pod, Choreo automatically adds a new replica to handle the increased load.

-

Free User - Scale to Zero

-

Enable scale to zero

-

For service components and web-apps you create after February 23, 2024, Choreo enables the scale-to-zero feature by default. When deploying or promoting the component, the deployment will automatically scale-to-zero. -Upon the next request to the deployed service, a replica will be created to serve the request.

-
-

Note

-
    -
  • For the services which contain at least one endpoint with the network visibility as Project, Choreo will not automatically scale-to-zero those components when you deploy or promote them.
    • -
  • HTTP services that run on a port other than the below list of ports will not automatically scale-to-zero your component when deploying or promoting: 5000, 6000, 7000, 8000, 9000, 7070 to 7079, 8080 to 8089, and 9090 to 9099 or 8290.
    • -
-
-

To enable scale-to-zero for service components created before February 23, 2024, follow the steps given below:

-
    -
  1. Sign in to the Choreo Console.
    2. -
  2. In the Component Listing pane, click on the component you want to scale-to-zero.
    3. -
  3. Make sure the component is deployed to an environment and is ready to receive traffic.
    4. -
  4. -

    In the left navigation menu, click DevOps and then click Scaling.

    -
      -
    • -

      If you are a free user, you will see a view similar to the one below. You can click the scale-to-zero card to enable scale-to-zero for your component.

      -

      Free User - Scale to Zero

      -
      • -
    • -

      If you are a paid user or you are running your applications in your own private data plane, you will see a view similar to the one below. You can click the scale-to-zero card to enable scale-to-zero for your component.

      -

      Paid User - Scale to Zero

      -
      • -
    -
    -

    Note

    -

    The scale-to-zero service should start within 60 seconds. If it doesn’t, the gateway will timeout the request.

    -
    -
    5. -
-

You can independently scale Choreo components in both the Development and Production environments. The deployment card indicates the scaling status of each environment. To configure the scale-to-zero feature for a specific environment, click on the scale-to-zero link, which redirects to the Devops → Scaling page.

-

Deploy View - Scale to Zero

-

When you turn on the scale-to-zero for your application, the minimum replicas for your app will be set to zero. However, you can still select an appropriate maximum number of replicas.

-

Limitations

-
    -
  • The scale-to-zero feature currently exclusively supports web applications and HTTP services. TCP and HTTPS services are not supported to be scaled to zero.
    • -
  • To scale to zero, your HTTP service must run on one of the specified ports: 5000, 6000, 7000, 8000, 9000, 7070 to 7079, 8080 to 8089, and 9090 to 9099 or 8290. If you have an endpoint in your component running in any other port, your component will not automatically scale-to-zero when deploying or promoting. Also, if you try to switch to the “scale-to-zero” option in the “Devops” → “Scaling” view, it will fail.
    • -
  • -

    Scheduled tasks and manually triggered components cannot connect to a service on a project scope if scale-to-zero is enabled. Attempting to do so results in the following error:

    -

    Host not found, not forwarding request.

    -

    To allow a task-type component to invoke a project-level service, set it to HPA mode if you are on a paid plan, or to no scaling if you are on the Developer plan.

    -
    • -
-

Architecture

-

When your Choreo application scales down to zero, an intermediary proxy service intercepts incoming requests. If a request is directed at your application, this service initiates a scale-up. Requests are held in the proxy's queue until your application becomes active. After scaling up, the proxy forwards the queued requests to your application.

-

If your application remains without HTTP traffic for an extended period (default idle time is 5 minutes), it will be scaled down to zero until more HTTP requests arrive. Conversely, if there's a surge in HTTP traffic to your scaled-up application, Choreo will further increase its scale to manage the demand. Choreo considers adding additional replicas if the number of queued requests surpasses the 'Target Pending Requests' threshold, which is set to 100 by default. You can adjust this threshold in the user interface.

-
-

Note

-

The initial request after a long period of inactivity experiences a delay because the application must first scale up from zero. If your API operates in a service-chain sequence (e.g., service-1 activates service-2, which in turn calls service-3), this waiting time may extend further. If your application or its chain takes a considerable time to scale up, be aware that the first request might face a timeout.

-
-

Troubleshooting

-

When Choreo enables scale-to-zero by default, it will configure the readiness probe with some default values. However, in some cases, you may observe that your first request responds with a 503 status code. To overcome these behaviors, fine-tune the readiness probe in the DevOps → Health Checks view to match your application's needs.

- - - - - - -
-
- - -
- - - -
- - -
- - - -
-
-
- - - - - - - - - - - - - - - - - \ No newline at end of file diff --git a/en/site/devops-and-ci-cd/builds-and-deployments/index.html b/en/site/devops-and-ci-cd/builds-and-deployments/index.html deleted file mode 100644 index 3837c1e10..000000000 --- a/en/site/devops-and-ci-cd/builds-and-deployments/index.html +++ /dev/null @@ -1,15 +0,0 @@ - - - - - - Redirecting... - - - - - - -Redirecting... - - diff --git a/en/site/devops-and-ci-cd/configure-container-resources-commands-and-arguments/index.html b/en/site/devops-and-ci-cd/configure-container-resources-commands-and-arguments/index.html deleted file mode 100644 index 2054c1e06..000000000 --- a/en/site/devops-and-ci-cd/configure-container-resources-commands-and-arguments/index.html +++ /dev/null @@ -1,3261 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - Configure Container Resources, Commands, and Arguments - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- - - -
- - - - - - -
- - -
- -
- - - - - - - -
-
- - - -
-
-
- - - - -
-
-
- - - -
-
-
- - - -
-
-
- - - -
-
- - - - - - - - - - - - - - - - - - - - -

Configure Container Resources, Commands, and Arguments

-

In Choreo, you can view detailed information about the container that comprises a component, such as its image tag, the corresponding commit ID, any imposed resource usage limits, and so on.

-

Each component in Choreo is limited to a single main container.

-

Container details

-
-

Resource Limits

-

Resource limits ensure that a single component does not take up more resources than it requires, which can affect other workloads on the data plane. If a process exceeds the allocated memory limit, the corresponding container will be forcefully shut down and restarted. If the process exceeds the allocated CPU limit, it gets throttled and can result in significant latencies in compute and I/O operations.

-
-

Choreo allows you to edit the default container configuration depending on your requirement.

-

Update container configurations

-

Follow these steps to update container configurations:

-
    -
  1. Sign in to the Choreo Console.
    2. -
  2. In the Component Listing pane, click on the component for which you want to edit container configurations.
    3. -
  3. In the left navigation menu, click DevOps and then click Containers.
    4. -
  4. On the Containers page, click Edit to update the corresponding container configuration.
    5. -
  5. -

    Apply the necessary changes and click Save.

    -

    Edit container configurations

    -
    6. -
-

The following topics walk you through the container configuration changes you can apply.

-

Update resource requests and limits

-
-

Note

-

The capability to update resource requests and limits is only available in paid pricing plans.

-
-

To update resource requests and limits, move the corresponding slider to a required position. A resource request cannot be less than its corresponding limit.

-

Set the image pull policy

-

You can select one of the following options as the image pull policy.

-
    -
  • Always: The image is always pulled from the container registry, even if a matching tag is already present in the data plane.
    • -
  • -

    If Not Present - The image is pulled from the container registry only if a matching image is not present in the data plane.

    -
    -

    Tip

    -

    The recommended option is If Not Present.

    -
    -
    • -
-

Specify container ports

-

You can specify appropriate values for the Container Port and Service Port. The Service Port is the port exposed outside of the container to your project-scoped endpoint. If you do not know the value to specify as the Service Port, specify the Container Port value in both fields.

-
-

Tip

-

You do not need to configure port values manually for Ballerina components. The capability to edit port values is primarily for containerized/Dockerfile-based components.

-
-

You can also select an appropriate Protocol.

-

Define a command and arguments for the container

-

You can define a command and arguments for a container when you want to provide or override the ENTRYPOINT of a container. For example, in a scenario where you want to run legacy or third-party applications, you would want to provide or override the ENTRYPOINT of a container.

-

Container command and arguments example

-

When you define a command and arguments,

-
    -
  • It specifies the ENTRYPOINT array and it is not executed within a shell.
    • -
  • Variable references $(VAR_NAME) are expanded using the container's environment. If a variable cannot be resolved, the reference in the input string will be unchanged.
    • -
  • $$ are reduced to $, which allows escaping the $(VAR_NAME) syntax. This means that "$$(VAR_NAME)" produces the string literal "$(VAR_NAME)".
    • -
  • Escaped references are never expanded, regardless of whether the variable exists or not.
    • -
-

The ENTRYPOINT of the container image is used if you do not define a command and arguments for the container.

- - - - - - -
-
- - -
- - - -
- - -
- - - -
-
-
- - - - - - - - - - - - - - - - - \ No newline at end of file diff --git a/en/site/devops-and-ci-cd/configure-storage/index.html b/en/site/devops-and-ci-cd/configure-storage/index.html deleted file mode 100644 index 508dc42ca..000000000 --- a/en/site/devops-and-ci-cd/configure-storage/index.html +++ /dev/null @@ -1,3272 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - Configure Storage - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- - - -
- - - - - - -
- - -
- -
- - - - - - - -
-
- - - -
-
-
- - - - -
-
-
- - - -
-
-
- - - -
-
-
- - - -
-
- - - - - - - - - - - - - - - - - - - - -

Configure Storage

-

All components you create in Choreo have a default read-only file system, which you cannot access or write to from your applications.

-

Volume mounts allow you to create either temporary or persisted writable file system storage locations for your applications.

-

Volume mount types

- - - - - - - - - - - - - - - - - - - - - -
TypeDescription
Empty Directory (In-Memory)A fast, temporary in-memory (tmpfs) storage location. This volume gets erased when you restart or remove the attached container. Available on all data planes.
Empty Directory (Disk)A temporary storage location on disk. This volume gets destroyed when you restart or remove the attached container. Only available on private data planes.
Persistent VolumeA permanent storage location. This volume persists even if you restart or remove the attached container. Only available on private data planes.
-
-

Tip

-

All components have a writable location in the /tmp directory at the time of component creation. You can also configure other writable locations if required.

-
-

Create a temporary storage space for your container

-

Empty directory (in-memory or on-disk) mounts allow you to create temporary file systems that your application can read from and write to. This option provides a convenient way to create a scratch space to write files temporarily before storing them in a more permanent storage location such as a cloud-backed storage bucket. -For example, unzipping a file, temporarily writing results from a memory-intensive operation to disk, a temporary local cache, etc. -However, it is important to note that these volumes destroy when you restart or update a container because the volumes are attached to the lifetime of a container.

-

Follow these steps to create a temporary storage space for your container:

-
    -
  1. Sign in to the Choreo Console.
    2. -
  2. In the Component Listing pane, click on the component for which you want to create a temporary storage.
    3. -
  3. In the left navigation menu, click DevOps and then click Storage.
    4. -
  4. Click + Create.
    5. -
  5. In the Create a Volume Mount pane, specify a name for the volume and select Empty Directory (In-Memory).
    6. -
-

Create temporary storage

-
    -
  1. -

    Click Next.

    -
    -

    In-memory (tmpfs) storage uses up container memory

    -

    Storage capacity for this type of volume will count against the container's memory limit.
    -Uncontrolled writes to this location may starve your application process of memory and can result in the container getting killed and restarted if the memory limits exceed.

    -
    -
    2. -
  2. -

    To add a mount location, specify a Mount Path and click Add mount.

    -
    -

    Tip

    -
      -
    • You can add multiple mount locations to a volume.
      • -
    • Mount paths should be absolute file paths and will be available to your application to read/write from.
      • -
    -
    -

    Specify mount details

    -
    3. -
  3. -

    Click Create. This applies the volume mount immediately to your container and triggers a rolling restart.

    -
    4. -
-

Create a persistent storage space for your container

-

Follow these steps to create a persistent storage space for your container:

-
-

Note

-

Persistent volume options are only available in private data plane organizations.

-
-
    -
  1. Sign in to the Choreo Console.
    2. -
  2. In the Component Listing pane, click on the component for which you want to create a persistent storage.
    3. -
  3. In the left navigation menu, click DevOps and then click Storage.
    4. -
  4. Click + Create.
    5. -
  5. In the Create a Volume Mount pane, specify a name for the volume and select Persistent Volume.
    6. -
  6. Select a Storage Class.
    7. -
  7. Move the Storage Capacity slider to set the required capacity.
    8. -
  8. -

    Select an appropriate Access Mode.

    -
    -

    Check and specify an access mode supported by the storage class

    -
      -
    • You must check the cloud provider documentation to select an appropriate access mode that the storage class supports. Choreo does not verify whether the storage class supports the access mode you select.
      • -
    • If the storage class does not support the access mode you select, it can result in a runtime mount error.
      • -
    -
    -

    Create persistent storage

    -
    9. -
  9. -

    Click Next.

    -
    10. -
  10. -

    To add a mount location, specify a Mount Path and click Add mount.

    -
    -

    Tip

    -
      -
    • You can add multiple mount locations to a volume.
      • -
    • Mount paths should be absolute file paths and will be available to your application to read/write from.
      • -
    -
    -
    11. -
  11. -

    Click Create. This applies the volume immediately to your container.

    -
    12. -
- - - - - - -
-
- - -
- - - -
- - -
- - - -
-
-
- - - - - - - - - - - - - - - - - \ No newline at end of file diff --git a/en/site/devops-and-ci-cd/configure-vpns-on-the-choreo-cloud-data-plane/index.html b/en/site/devops-and-ci-cd/configure-vpns-on-the-choreo-cloud-data-plane/index.html deleted file mode 100644 index 19a2960f7..000000000 --- a/en/site/devops-and-ci-cd/configure-vpns-on-the-choreo-cloud-data-plane/index.html +++ /dev/null @@ -1,3614 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - Configure VPNs on the Choreo Cloud Data Plane - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- - - -
- - - - - - -
- - -
- -
- - - - - - - -
-
- - - -
-
-
- - - - -
-
-
- - - -
-
-
- - - -
-
-
- - - -
-
- - - - - - - - - - - - - - - - - - - - -

Configure VPNs on the Choreo Cloud Data Plane

-

Secure access to private networks from the Choreo cloud data plane is an essential use case for cloud data plane users.

-

Choreo allows this secure connection using Tailscale. For this, Choreo provides a prebuilt Tailscale image component that can act as a forward proxy, which you can deploy in your Choreo project as a service. This service allows you to forward traffic to your external networks via Tailscale’s peer-to-peer WireGuard network.

-

The following diagram illustrates the high-level deployment architecture of the Tailscale pre-installed forward proxy:

-

Deployment architecture

-

Let's take a look at the specifics of each part to understand the deployment architecture.

-
    -
  • -

    Choreo project

    -

    In Choreo, a project groups various components. For more information on what a project in Choreo is, see the documentation on Project.

    -
    • -
  • -

    Tailscale proxy

    -

    This acts as the Tailscale pre-installed forward proxy, facilitating secure peer-to-peer WireGuard connections from the Choreo cloud data plane to private networks. It includes a Tailscale Daemon, SOCKS5 proxy, and a configurable TCP forwarder.

    -
      -
    • -

      Tailscale daemon

      -

      This is the core component of Tailscale. It is a software service that provides secure network connectivity and private networking solutions. For more details see the Tailscale documentation.

      -
      • -
    • -

      SOCKS5 proxy

      -

      This uses Tailscale’s userspace networking mode, rather than the kernel mode. Therefore, the inbuilt SOCKS5 proxy handles the forwarded traffic and directs it through the Tailscale network.

      -
      • -
    • -

      TCP forwarder

      -

      Forwards inbound TCP (transmission control protocol) traffic from the Tailscale proxy container’s network interface to the SOCKS5 proxy, ensuring it reaches its destination via the secured WireGuard tunnel.

      -
      • -
    -
    • -
  • -

    User applications and the Choreo API gateway

    -

    User applications within the same namespace (project) can use the Kubernetes service created to front the Tailscale proxy, for connecting to the corresponding private endpoints. You can either expose this service within the organization via the internal API gateway or expose it to the public via the external API gateway. For more details, see the documentation on Choreo endpoints.

    -
    • -
-
- -

Now that you understand the deployment architecture, let’s explore how you can use Tailscale to secure connections to your private networks.

-

Configure and use Tailscale to access private network endpoints

-

This section walks you through the steps to create, configure, deploy, and use the Tailscale proxy component.

-

Tailscale proxy deployment

-

Let's get started.

-

Prerequisites

-
    -
  • Understand the basics of how Tailscale works.
    • -
  • Have a Tailscale account (Tailnet). There are multiple plans available for you to set up your Tailscale network. For details, see Tailscale plans.
    • -
  • Install Tailscale and connect your private data center or server to it, so that your private services are accessible via your Tailscale network. To quickly get started with Tailscale, see the Tailscale quickstart.
    • -
  • -

    If you are signing in to the Choreo Console for the first time, create an organization as follows:

    -
      -
    1. Go to https://console.choreo.dev/, and sign in using your Google, GitHub, or Microsoft account.
      2. -
    2. Enter a unique organization name. For example, Stark Industries.
      3. -
    3. Read and accept the privacy policy and terms of use.
      4. -
    4. Click Create.
      5. -
    -

    This creates the organization and opens the organization home page.

    -
    • -
-

Step 1: Create the Tailscale proxy

-

Step 1.1: Create a project

-

Follow the steps given below to create a project:

-
    -
  1. Go to https://console.choreo.dev/ and sign in. This opens the organization home page.
    2. -
  2. On the organization home page, click + Create Project.
    3. -
  3. -

    Enter a display name, unique name, and description for the project. You can enter the values given below:

    -
    -

    Info

    -

    In the Name field, you must specify a name to uniquely identify your project in various contexts. The value is editable only at the time you create the project. You cannot change the name after you create the project.

    -
    - - - - - - - - - - - - - - - - - - - - - -
    FieldValue
    Project Display NameTailscale Proxy Project
    Nametailscale-proxy-project
    Project DescriptionMy Tailscale project
    -
    4. -
  4. -

    Click Create. This creates the project and takes you to the project home page.

    -
    5. -
-

Step 1.2: Create the Tailscale proxy component

-
    -
  1. On the project home page, click Service under Create a Component.
    2. -
  2. -

    Enter a display name, component name, and a description for the service. For this guide, let's enter the following values:

    - - - - - - - - - - - - - - - - - - - - - -
    FieldValue
    Component Display NameTailscale proxy
    Component Nametailscale-proxy
    DescriptionTailscale proxy component
    -
    3. -
  3. -

    Click the Container Registry tab.

    -
    4. -
  4. In the Container Registry list, select Choreo Samples Registry.
    5. -
  5. Click the Tailscale Proxy card.
    6. -
  6. Click Create.
    7. -
-

Now you have successfully created the Tailscale proxy. You can proceed to configure and deploy it.

-

Step 2: Configure and deploy the Tailscale proxy

-

Here, you will add the required volume mounts, set the Tailscale authentication key, configure the TCP forwarder, configure endpoints, and deploy the Tailscale proxy. Follow the steps given below:

-

Step 2.1: Add required volume mounts

-

Tailscale requires the following volume mounts for its operations:

-
    -
  • /var/run/tailscale
    • -
  • /.local
    • -
-

To create the volume mounts, follow the step-by-step instructions in Configure Storage.

-

Step 2.2: Configure and deploy the component

-

To configure and deploy the component, follow the steps given below:

-
    -
  1. In the left navigation menu, click Deploy.
    2. -
  2. On the Build Area card, click Configure & Deploy.
    3. -
  3. In the Environment Configurations pane that opens, click + Add and add the TS_AUTH_KEY environment variable as a secret. To add the environment variable, you must obtain an authentication key from your Tailscale network.
      -
    • For details on how to obtain an authentication key from your Tailscale network, see Auth keys in the Tailscale documentation.
      • -
    -
    4. -
  4. Click Next.
    5. -
  5. In the File Mount pane that opens, click + Add.
    6. -
  6. -

    To mount a configuration file to the Tailscale proxy component and specify the port mapping for the TCP forward proxy running there, do the following:

    -
      -
    1. Specify /config.yaml as the Mount Path.
      2. -
    2. -

      Specify the following in the sample configuration file: - 

      portMappings:
-    8080: "100.108.78.93:8090"
-    8081: "100.108.78.93:1433"
-

      -
      -

      Note

      -

      In this sample configuration, the TCP traffic arriving at port 8080 on your Tailscale proxy will be forwarded to port 8090 on the node with IP address 100.108.78.93 in your Tailscale network. Similarly, port 8081 will map to the corresponding address. You can find the IP addresses of your nodes on the Tailscale machines page in your Tailscale network's admin console or via the Tailscale clients running on your machine.

      -
      -
      3. -
    -
    7. -
  7. -

    Click Next.

    -
    8. -
  8. -

    In the Endpoints pane that opens, click + Add and edit the endpoints.yaml configuration to expose your Tailscale proxy as a service. The following is a sample endpoints.yaml configuration you can use:

    -
    -

    Note

    -

    The sample endpoints.yaml file given below defines two project-level endpoints. These endpoints can be used by other components within the same project to access the services. If you want to directly expose your private endpoint via the Choreo gateway either with the Public or Organization visibility, you can set the networkVisibility property of the endpoint to Public or Organization.

    -
    -
    version: 0.1
-endpoints:
-  - name: Private HTTP service
-    port: 8080
-    type: REST
-    networkVisibility: Project
-    context: /
-  - name: Private DB service
-    port: 8081
-    type: TCP
-    networkVisibility: Project
-    context: /
-
    - -
    9. -
  9. -

    Click Save.

    -
    10. -
  10. -

    Click Next and then click Deploy.

    -
    -

    Note

    -

    Deploying the component may take a while. You can track the progress by observing the logs. Once the deployment is complete, the build status changes to Active on the Development environment card.

    -
    -
    11. -
-

When the component is deployed, you can observe a new node connected to your Tailscale network. To view this, go to the Tailscale machines page of your Tailscale coordination server.

-

Step 3: Access private network endpoints with the Tailscale proxy

-

Now you have successfully deployed the Tailscale proxy in your project and it is connected to your Tailnet. You can proceed to use the Tailscale proxy to provision access for other components to securely access private network endpoints.

-

You can configure endpoints of the Tailscale proxy to use it for various aspects within Choreo.

-

Post-deployment actions

-

Handle node key expiry

-

Tailscale nodes have a default node key expiry time of 180 days. Nodes require re-authentication after key expiry to avoid connection losses and application downtime. There is an option to disable node key expiry if necessary. For more details, see Node key expiry documentation.

-

Handle auth key expiry

-

Auth keys are used to register new nodes into your Tailscale network. The default expiry time for auth keys is 90 days, but nodes remain connected even after auth key expiry. This becomes an issue only if the Tailscale Proxy component is redeployed or restarted.

-

Update port mapping configurations

-

If you want to add a new private endpoint to your network and access it via the same Tailscale proxy within Choreo, you must add a new port mapping entry in the port mapping configuration of your Tailscale proxy deployment.

-

Best practices

-

Configure health checks

-

Since the Tailscale proxy acts as a forward proxy, it is important to configure health checks. You can use one of the open ports of the TCP forwarder as a health endpoint. For details on how to set up health probes in Choreo, see Set up health checks.

-

Use Tailscale ACLs

-

You can use Tailscale ACLs to precisely manage permission for users and devices on your Tailnet.

-

Disable scale-to-zero for the Tailscale proxy

-

It is recommended to disable Scale-to-Zero for the Tailscale proxy because it acts as a forward proxy and should always be up and running to make consistent connections with the Tailscale VPN mesh. -If you enable Scale-to-Zero, you may experience service downtime.

-

Run multiple replicas with HPA (horizontal pod autoscaler)

-

To achieve high availability and resiliency for the Tailscale proxy, you must run multiple replicas with HPA. To configure multiple replicas for the Tailscale proxy component, go to the Scaling page under DevOps. For more details, see Autoscale component replicas

-

Security best practices

-

Before deploying the Tailscale proxy in production environments, it is recommended to follow the Tailscale production best practices and security best practices.

-
-

Note

-

Choreo blocks incoming connections from other nodes in your Tailnet to the Tailscale proxy to prevent access to your project’s namespace in the Choreo cloud data plane.

-
-

Troubleshoot issues

-

For assistance in resolving common Tailscale proxy issues, see Troubleshoot Tailscale proxy issues.

- - - - - - -
-
- - -
- - - -
- - -
- - - -
-
-
- - - - - - - - - - - - - - - - - \ No newline at end of file diff --git a/en/site/devops-and-ci-cd/manage-configurations-and-secrets/index.html b/en/site/devops-and-ci-cd/manage-configurations-and-secrets/index.html deleted file mode 100644 index 06c17b426..000000000 --- a/en/site/devops-and-ci-cd/manage-configurations-and-secrets/index.html +++ /dev/null @@ -1,3320 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - Manage Configurations and Secrets - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- - - -
- - - - - - -
- - -
- -
- - - - - - - -
-
- - - -
-
-
- - - - -
-
-
- - - -
-
-
- - - -
-
-
- - - -
-
- - - - - - - - - - - - - - - - - - - - -

Manage Configurations and Secrets

-

Choreo allows you to easily manage and version your component's configurations and secrets as file mounts or environment variables.

-
-

Note

-

All configurations and secrets applied to a Choreo component are stored in an encrypted secret vault in the cloud data plane, which is managed by WSO2. -If you are on a private data plane, the configurations and secrets are stored in an Azure key vault or AWS secret manager attached to your data plane in your cloud environment.

-
-

The difference between configurations and secrets

-

Choreo considers all configurations and secrets to be sensitive content when storing them, but gives you the option to choose between secret or configuration when you create a file mount or an environment variable.

-
    -
  • Secrets are write-only. Once you create a secret, you cannot see or retrieve its content via the Choreo Console. However, you can overwrite the existing content at any time.
    • -
  • -

    Configurations can be read and updated via the Choreo Console after you create them.

    -
    -

    Note

    -

    If you want to include sensitive data such as database passwords, cloud credentials, service accounts, and so on, the recommended approach is to use a secret instead of a configuration.

    -
    -
    • -
-

Apply a file mount to your container

-

Follow these steps to apply a file mount to a component you have created:

-
    -
  1. Sign in to the Choreo Console.
    2. -
  2. In the Component Listing pane, click on the component for which you want to define configurations and secrets.
    3. -
  3. In the left navigation menu, click DevOps and then click Configs & Secrets.
    4. -
  4. Click + Create.
    5. -
  5. In the Create a Config or Secret pane, click File Mount.
    6. -
  6. -

    If you want to create the file mount as a secret, select Mark as a Secret. Otherwise, proceed to the next step.

    -
    -

    Note

    -

    If you create the file mount as a secret, you will not be able to read the file content after you create the file mount.

    -
    -
    7. -
  7. -

    In the Display Name field, specify a name for the file mount.

    -
    -

    Tip

    -

    The display name does not affect the file mount or its content. It is only a reference to identify the configuration or secret you create.

    -
    -
    8. -
  8. -

    In the File Mount Path field, specify where to mount the file inside the container. Use an absolute file path with the file name and extension if applicable.

    -
    -

    Tip

    -

    The file name in the mount path does not need to match the configuration name or the name of the file you upload.

    -
    -
    9. -
  9. -

    Upload a configuration file or copy and paste the configuration content into the editor.

    -
    10. -
  10. -

    Click Create.

    -
    -

    Note

    -

    Configurations and secrets are applied immediately to your environment on creation. To ensure that the container reflects the new content, your existing running replicas undergo a rolling restart.

    -
    -
    11. -
-

Apply environment variables to your container

-

Follow these steps to apply environment variables to a component you have created:

-
    -
  1. Sign in to the Choreo Console.
    2. -
  2. In the Component Listing pane, click on the component for which you want to define configurations and secrets.
    3. -
  3. In the left navigation menu, click DevOps and then click Configs & Secrets.
    4. -
  4. Click + Create.
    5. -
  5. In the Create a Config or Secret pane, click Environment Variables.
    6. -
  6. -

    If you want to create the environment variable values as secrets, select Mark as a Secret. Otherwise, proceed to the next step.

    -
    -

    Note

    -

    If you create environment variables as secrets, you will not be able to read the values you set for the environment variables after you create them.

    -
    -
    7. -
  7. -

    In the Display Name field, specify a name to identify the configuration or secret.

    -
    -

    Tip

    -

    The display name you specify does not affect the environment variables you set. It is only a reference to identify the configuration or secret you create.

    -
    -
    8. -
  8. -

    Under Add Environment Variables, specify the necessary environment variables as key-value pairs. You can click Add Item to add any number of environment variables.

    -
    9. -
  9. -

    Click Create.

    -
    10. -
-

Update an existing configuration or secret

-

Follow these steps to update a configuration or secret you have defined:

-
    -
  1. Sign in to the Choreo Console.
    2. -
  2. In the Component Listing pane, click on the component for which you want to update configurations and secrets.
    3. -
  3. In the left navigation menu, click DevOps and then click Configs & Secrets.
    4. -
  4. Click the edit icon corresponding to the configuration or secret you want to update.
    5. -
  5. Apply the necessary changes and click Save.
    6. -
-

Delete an existing configuration or secret

-

Follow these steps to delete a configuration or secret you have defined:

-
    -
  1. Sign in to the Choreo Console.
    2. -
  2. In the Component Listing pane, click on the component for which you want to delete configurations and secrets.
    3. -
  3. In the left navigation menu, click DevOps and then click Configs & Secrets.
    4. -
  4. Click the delete icon corresponding to the configuration or secret you want to delete.
    5. -
  5. Enter the name of the configuration or secret to confirm deletion.
    6. -
  6. Click Delete.
    7. -
-

Manage Ballerina configurables

-

Choreo manages the Ballerina configurables for the Ballerina components you create.

-

When you deploy or promote a Ballerina application, you can modify the Ballerina configurables via the Deploy page.

-
-

Tip

-

You can use configurables instead of environment variables to add file mounts to a Ballerina component. - Environment variables are primarily for components written in other languages.

-
- - - - - - -
-
- - -
- - - -
- - -
- - - -
-
-
- - - - - - - - - - - - - - - - - \ No newline at end of file diff --git a/en/site/devops-and-ci-cd/manage-environments/index.html b/en/site/devops-and-ci-cd/manage-environments/index.html deleted file mode 100644 index 0dad73545..000000000 --- a/en/site/devops-and-ci-cd/manage-environments/index.html +++ /dev/null @@ -1,3254 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - Manage Environments - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- - - -
- - - - - - -
- - -
- -
- - - - - - - -
-
- - - -
-
-
- - - - -
-
-
- - - -
-
-
- - - -
-
-
- - - -
-
- - - - - - - - - - - - - - - - - - - - -

Manage Environments

-

By default, all projects created in the cloud data planes (irrespective of the data plane region) are provisioned with two environments (i.e., development and production).

-

The environments are listed in the order of deployment and promotion. The initial deployment takes place in the first environment and you can proceed to promote a component to subsequent environments.

-

Create a new environment

-

Prerequisites

-
    -
  • To create additional environments, you must have a Choreo subscription or a private data plane.
    • -
  • To create a new environment in a private data plane organization, you must have the ENVIRONMENT-MANAGEMENT permission. By default, ENVIRONMENT-MANAGEMENT permission is granted to Admin and Choreo DevOps roles.
    • -
-

To create a new environment, follow the steps given below:

-
    -
  1. Sign in to the Choreo Console and switch to the organization where you want to create a new project.
    2. -
  2. In the left navigation menu, click DevOps and then click Environments (note that this is the Environments page under your organization, not your projects).
    3. -
  3. -

    On the Environments page, click Create and specify the following details to create a new environment:

    -
      -
    • Name: A display name for the new environment.
      • -
    • -

      Data Plane - The data plane to create the new environment.

      -
      -

      Tip

      -

      The Data Plane list displays all the private data planes registered under your organization.

      -
      -
      • -
    • -

      DNS Prefix: A DNS prefix to identify the exposed APIs in the environment. Here, the base domain depends on the custom domain attached to the API gateways provisioned on the selected data plane.

      -
      • -
    • -

      Mark environment as a Production environment: Select if you want this environment to be a production environment.

      -
      -

      Tip

      -

      In Choreo, you can have multiple non-production and production environments. To work in a production environment, you must have privileged permissions to access and deploy to production environments.

      -
      -
      • -
    -
    4. -
-

Change the order of promotion

-

The order in which environments are listed on the Environments page is the same order in which promotion takes place.

-

To change the order of promotion across environments in an organization, follow the steps given below:

-
    -
  1. Sign in to the Choreo Console and switch to the organization for which you want to change the order of promotion.
    2. -
  2. In the left navigation menu, click DevOps and then click Environments.
    3. -
  3. -

    On the Environments page, click and drag environment list items to rearrange the order of listed environments.

    -
    -

    Note

    -

    Although changes to the order of promotion for environments are applied immediately, the change does not affect the components already running in environments. Only subsequent builds and promotions will follow the new order.

    -
    -
    4. -
-

To see the changes, go to the Deploy page of a component (in any project).

-

Delete an environment

-

To delete an environment, follow the steps given below:

-
-

Warning

-

Environment deletion is a permanent, non-reversible operation.

-
-
    -
  1. Sign in to the Choreo Console and switch to your organization.
    2. -
  2. In the left navigation menu, click DevOps and then click Environments.
    3. -
  3. In the Environments list, click the delete icon corresponding to the environment you want to delete. This displays a confirmation dialog with details on the impact of deletion.
    4. -
  4. Review the details, then type the environment name to confirm the deletion.
    5. -
  5. Click Delete.
    6. -
- - - - - - -
-
- - -
- - - -
- - -
- - - -
-
-
- - - - - - - - - - - - - - - - - \ No newline at end of file diff --git a/en/site/devops-and-ci-cd/set-up-health-checks/index.html b/en/site/devops-and-ci-cd/set-up-health-checks/index.html deleted file mode 100644 index 866e8fa63..000000000 --- a/en/site/devops-and-ci-cd/set-up-health-checks/index.html +++ /dev/null @@ -1,3284 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - Set Up Health Checks - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- - - -
- - - - - - -
- - -
- -
- - - - - - - -
-
- - - -
-
-
- - - - -
-
-
- - - -
-
-
- - - -
-
-
- - - -
-
- - - - - - - - - - - - - - - - - - - - -

Set Up Health Checks

-

Health checks ensure that a running container is always healthy and ready to serve traffic.

-

Liveness probes

-

Liveness probes run periodically on your container and restart if the probe fails. -This allows the container to self-heal in scenarios where the application may have crashed or become unresponsive.

-

Readiness probes

-

Similar to liveness probes, readiness probes run periodically throughout the lifecycle of a container. -However, unlike liveness probes, these probes do not restart the container if the probe fails. Instead, they stop the container from receiving network traffic.

-
-

Readiness probes on single replicas

-

You must be mindful when you configure readiness probes on a single-running replica. If the readiness probe fails, your application stops receiving traffic because there is only one active replica. The application may not recover unless the liveness probe fails and restarts the container.

-
-

Probe types

-

You can configure the following probe types for both readiness and liveness probes.

-

HTTP GET request

-

This probe sends an HTTP GET request to a specified port and path on the container. A response status code in the range of 200-399 indicates that the request is a success.

-

Depending on your requirement, you can configure additional HTTP headers.

-

The recommended approach is to create a /healthz or /health endpoint in your service for this purpose.

-

HTTP GET probe

-

TCP connection probe

-

This probe attempts to open a socket to the container on the specified port. If it cannot establish a TCP connection, it becomes a failure.

-

Execute a command

-

This probe executes a given script inside the container. A non-zero return from the command is considered a failure.

-

For example, ["cat", "/tmp/healthy"] is considered healthy if the file /tmp/healthy is present. If not, it becomes a failure (non-zero exit code). -In such scenarios, the application is responsible for writing and maintaining this file in the specified location.

-

Configure liveness and readiness probes

-

Follow these steps to configure liveness and readiness probes on a container:

-
    -
  1. Sign in to the Choreo Console.
    2. -
  2. In the Component Listing pane, click on the component for which you want to configure liveness and readiness probes.
    3. -
  3. In the left navigation menu, click DevOps and then click Health Checks.
    4. -
  4. On the Health Checks page, click + Create.
    5. -
  5. -

    Configure the liveness probe depending on your requirement.

    -

    Configure probe

    -
    6. -
  6. -

    Click Save.

    -
    7. -
  7. Configure the readiness probe depending on your requirement.
    8. -
  8. -

    Click Save.

    -
    -

    Note

    -

    You can update or remove a probe at any time.

    -
    -
    9. -
-

Follow these steps to ensure that the container works as expected:

-
    -
  1. In the left navigation menu, click Runtime under DevOps.
    2. -
  2. On the Runtime page, check the details to confirm that the container works as expected. If the container does not start, check the events and conditions to see if any of the probes are causing the container to fail.
    3. -
- - - - - - -
-
- - -
- - - -
- - -
- - - -
-
-
- - - - - - - - - - - - - - - - - \ No newline at end of file diff --git a/en/site/devops-and-ci-cd/view-runtime-details/index.html b/en/site/devops-and-ci-cd/view-runtime-details/index.html deleted file mode 100644 index 28cecc719..000000000 --- a/en/site/devops-and-ci-cd/view-runtime-details/index.html +++ /dev/null @@ -1,3241 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - View Runtime Details - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- - - -
- - - - - - -
- - -
- -
- - - - - - - -
-
- - - -
-
-
- - - - -
-
-
- - - -
-
-
- - - -
-
-
- - - -
-
- - - - - - - - - - - - - - - - - - - - -

View Runtime Details

-

In Choreo, you can view details about running replicas of a component in a specific environment (i.e., Development or Production).

-

To view the runtime details of a component, follow the steps given below:

-
    -
  1. Sign in to the Choreo Console.
    2. -
  2. In the Component Listing pane, click on the component for which you want to view runtime details.
    3. -
  3. In the left navigation menu, click DevOps and then click Runtime. This opens the Runtime page populated with data retrieved from the underlying Choreo data plane.
    4. -
-

Runtime details

-

The runtime details you can see here are analogous to a zoomed-in view of a specific environment on the Deploy page.

-

The following topics walk you through the specific details you can view and actions you can perform via the Runtime page.

-

Redeploy a release

-

On the Runtime page, you can click Redeploy Release to immediately redeploy all resources, including configurations and secrets, to a specific environment. This triggers a rolling update to sync all the latest changes to the data plane.

-
-

What is a release?

-

A release in Choreo uniquely identifies an underlying deployment of a component to an environment for a given version. For example, if you deploy a component to two environments across two versions, the component will have four active releases.

-
-

The capability to redeploy a release also allows you to quickly restart all the running replicas of a component in a specific environment.

-

View running instances

-

The running instances you see on the Runtime page provide insights into the active replicas of your component in the selected environment.

-
    -
  • You can view details of each active replica and its associated real-time CPU and memory usage, status, restarts, and the time of the last activity.
    • -
  • -

    If you want to see the real-time logs and information on conditions and events of a replica, click the menu icon of the replica and then click Real-time Logs or Conditions & Events depending on what you need to view. These options provide insights that help to diagnose issues in deployments.

    -

    Running instances

    -
    -

    Note

    -
      -
    • All metrics such as the total and replica-level CPU and memory usage displayed on the Runtime page are real-time data and are instantaneous representations of a component's current state.
      • -
    • You can take a look at the observability metrics of a component to see historical data and usage trends.
      • -
    -
    -
    • -
-

Observe real-time container logs

-

Unlike the logs available in the Observability Metrics of a component, these logs are fetched in real-time from the data plane and are not historical. Therefore, you can only see logs of active containers and the last shutdown container.

-

Real-time container logs

-
    -
  • Display Previous Logs: Enable to retrieve logs from the last shutdown/crashed/restarted container of an instance.
    • -
  • Since Seconds: Specify the duration in seconds to fetch corresponding logs.
    • -
  • Filter Logs: Enable to filter and displays matching log lines. This is a fuzzy string search.
    • -
-

View container conditions and events

-

Conditions and events provide information necessary to troubleshoot failing deployments.

-

Container conditions and events

-

If a component is not behaving as expected and you cannot detect any issues via the application logs, these events can provide necessary debugging information, such as the following:

-
    -
  • Failing health checks (liveness and readiness probes).
    • -
  • Missing or invalid configuration/secret mounts.
    • -
  • Missing or invalid storage volume mounts.
    • -
  • Scheduling issues in the underlying data plane.
    • -
- - - - - - -
-
- - -
- - - -
- - -
- - - -
-
-
- - - - - - - - - - - - - - - - - \ No newline at end of file diff --git a/en/site/get-started/build-your-first-cloud-native-application-with-choreo/index.html b/en/site/get-started/build-your-first-cloud-native-application-with-choreo/index.html deleted file mode 100644 index 1bab0eb3b..000000000 --- a/en/site/get-started/build-your-first-cloud-native-application-with-choreo/index.html +++ /dev/null @@ -1,15 +0,0 @@ - - - - - - Redirecting... - - - - - - -Redirecting... - - diff --git a/en/site/get-started/quick-start-guide/index.html b/en/site/get-started/quick-start-guide/index.html deleted file mode 100644 index d6b0fce67..000000000 --- a/en/site/get-started/quick-start-guide/index.html +++ /dev/null @@ -1,15 +0,0 @@ - - - - - - Redirecting... - - - - - - -Redirecting... - - diff --git a/en/site/get-started/tutorials/create-your-first-containerized-service-component/index.html b/en/site/get-started/tutorials/create-your-first-containerized-service-component/index.html deleted file mode 100644 index 01f424356..000000000 --- a/en/site/get-started/tutorials/create-your-first-containerized-service-component/index.html +++ /dev/null @@ -1,15 +0,0 @@ - - - - - - Redirecting... - - - - - - -Redirecting... - - diff --git a/en/site/get-started/tutorials/create-your-first-event-triggered-integration/index.html b/en/site/get-started/tutorials/create-your-first-event-triggered-integration/index.html deleted file mode 100644 index 661c5de8a..000000000 --- a/en/site/get-started/tutorials/create-your-first-event-triggered-integration/index.html +++ /dev/null @@ -1,15 +0,0 @@ - - - - - - Redirecting... - - - - - - -Redirecting... - - diff --git a/en/site/get-started/tutorials/create-your-first-integration-as-an-api/index.html b/en/site/get-started/tutorials/create-your-first-integration-as-an-api/index.html deleted file mode 100644 index 615ee5353..000000000 --- a/en/site/get-started/tutorials/create-your-first-integration-as-an-api/index.html +++ /dev/null @@ -1,15 +0,0 @@ - - - - - - Redirecting... - - - - - - -Redirecting... - - diff --git a/en/site/get-started/tutorials/create-your-first-rest-api-proxy/index.html b/en/site/get-started/tutorials/create-your-first-rest-api-proxy/index.html deleted file mode 100644 index 2dcb90eb6..000000000 --- a/en/site/get-started/tutorials/create-your-first-rest-api-proxy/index.html +++ /dev/null @@ -1,15 +0,0 @@ - - - - - - Redirecting... - - - - - - -Redirecting... - - diff --git a/en/site/get-started/tutorials/create-your-first-rest-api/index.html b/en/site/get-started/tutorials/create-your-first-rest-api/index.html deleted file mode 100644 index d6b0fce67..000000000 --- a/en/site/get-started/tutorials/create-your-first-rest-api/index.html +++ /dev/null @@ -1,15 +0,0 @@ - - - - - - Redirecting... - - - - - - -Redirecting... - - diff --git a/en/site/get-started/tutorials/create-your-first-webhook/index.html b/en/site/get-started/tutorials/create-your-first-webhook/index.html deleted file mode 100644 index 8cddf1c85..000000000 --- a/en/site/get-started/tutorials/create-your-first-webhook/index.html +++ /dev/null @@ -1,15 +0,0 @@ - - - - - - Redirecting... - - - - - - -Redirecting... - - diff --git a/en/site/get-started/tutorials/deploy-a-containerized-application-as-an-event-triggered-integration/index.html b/en/site/get-started/tutorials/deploy-a-containerized-application-as-an-event-triggered-integration/index.html deleted file mode 100644 index 71782578a..000000000 --- a/en/site/get-started/tutorials/deploy-a-containerized-application-as-an-event-triggered-integration/index.html +++ /dev/null @@ -1,15 +0,0 @@ - - - - - - Redirecting... - - - - - - -Redirecting... - - diff --git a/en/site/get-started/tutorials/secure-an-api-with-role-based-access-control/index.html b/en/site/get-started/tutorials/secure-an-api-with-role-based-access-control/index.html deleted file mode 100644 index 3d59ba7a9..000000000 --- a/en/site/get-started/tutorials/secure-an-api-with-role-based-access-control/index.html +++ /dev/null @@ -1,15 +0,0 @@ - - - - - - Redirecting... - - - - - - -Redirecting... - - diff --git a/en/site/get-started/what-is-choreo/index.html b/en/site/get-started/what-is-choreo/index.html deleted file mode 100644 index bd71d2425..000000000 --- a/en/site/get-started/what-is-choreo/index.html +++ /dev/null @@ -1,15 +0,0 @@ - - - - - - Redirecting... - - - - - - -Redirecting... - - diff --git a/en/site/graphql-api/index.html b/en/site/graphql-api/index.html deleted file mode 100644 index 2028df1e0..000000000 --- a/en/site/graphql-api/index.html +++ /dev/null @@ -1,15 +0,0 @@ - - - - - - Redirecting... - - - - - - -Redirecting... - - diff --git a/en/site/insights/choreo-insights-api/index.html b/en/site/insights/choreo-insights-api/index.html deleted file mode 100644 index 20ba0d419..000000000 --- a/en/site/insights/choreo-insights-api/index.html +++ /dev/null @@ -1,15 +0,0 @@ - - - - - - Redirecting... - - - - - - -Redirecting... - - diff --git a/en/site/insights/configure-alerts/index.html b/en/site/insights/configure-alerts/index.html deleted file mode 100644 index 596d3c98d..000000000 --- a/en/site/insights/configure-alerts/index.html +++ /dev/null @@ -1,15 +0,0 @@ - - - - - - Redirecting... - - - - - - -Redirecting... - - diff --git a/en/site/insights/generate-custom-reports/index.html b/en/site/insights/generate-custom-reports/index.html deleted file mode 100644 index 5d5d36567..000000000 --- a/en/site/insights/generate-custom-reports/index.html +++ /dev/null @@ -1,15 +0,0 @@ - - - - - - Redirecting... - - - - - - -Redirecting... - - diff --git a/en/site/insights/programmatic-access-choreo-insights-api/index.html b/en/site/insights/programmatic-access-choreo-insights-api/index.html deleted file mode 100644 index 97170bf00..000000000 --- a/en/site/insights/programmatic-access-choreo-insights-api/index.html +++ /dev/null @@ -1,15 +0,0 @@ - - - - - - Redirecting... - - - - - - -Redirecting... - - diff --git a/en/site/insights/view-api-insights/index.html b/en/site/insights/view-api-insights/index.html deleted file mode 100644 index cf6928035..000000000 --- a/en/site/insights/view-api-insights/index.html +++ /dev/null @@ -1,15 +0,0 @@ - - - - - - Redirecting... - - - - - - -Redirecting... - - diff --git a/en/site/ipaas/ballerina/create-your-first-event-triggered-integration/index.html b/en/site/ipaas/ballerina/create-your-first-event-triggered-integration/index.html deleted file mode 100644 index 15101c383..000000000 --- a/en/site/ipaas/ballerina/create-your-first-event-triggered-integration/index.html +++ /dev/null @@ -1,15 +0,0 @@ - - - - - - Redirecting... - - - - - - -Redirecting... - - diff --git a/en/site/ipaas/ballerina/develop-integrations-with-ballerina/index.html b/en/site/ipaas/ballerina/develop-integrations-with-ballerina/index.html deleted file mode 100644 index 615ee5353..000000000 --- a/en/site/ipaas/ballerina/develop-integrations-with-ballerina/index.html +++ /dev/null @@ -1,15 +0,0 @@ - - - - - - Redirecting... - - - - - - -Redirecting... - - diff --git a/en/site/ipaas/get-started-with-choreo-ipaas/index.html b/en/site/ipaas/get-started-with-choreo-ipaas/index.html deleted file mode 100644 index 615ee5353..000000000 --- a/en/site/ipaas/get-started-with-choreo-ipaas/index.html +++ /dev/null @@ -1,15 +0,0 @@ - - - - - - Redirecting... - - - - - - -Redirecting... - - diff --git a/en/site/ipaas/micro-integrator/create-your-first-integration/index.html b/en/site/ipaas/micro-integrator/create-your-first-integration/index.html deleted file mode 100644 index 615ee5353..000000000 --- a/en/site/ipaas/micro-integrator/create-your-first-integration/index.html +++ /dev/null @@ -1,15 +0,0 @@ - - - - - - Redirecting... - - - - - - -Redirecting... - - diff --git a/en/site/ipaas/micro-integrator/develop-integrations-with-integration-studio/index.html b/en/site/ipaas/micro-integrator/develop-integrations-with-integration-studio/index.html deleted file mode 100644 index 9dbb1230c..000000000 --- a/en/site/ipaas/micro-integrator/develop-integrations-with-integration-studio/index.html +++ /dev/null @@ -1,15 +0,0 @@ - - - - - - Redirecting... - - - - - - -Redirecting... - - diff --git a/en/site/js/open_in_new_tab.js b/en/site/js/open_in_new_tab.js deleted file mode 100644 index 964fb4c1e..000000000 --- a/en/site/js/open_in_new_tab.js +++ /dev/null @@ -1,45 +0,0 @@ -// Description: Open external links in a new tab and PDF links in a new tab -// Source: https://jekyllcodex.org/without-plugin/new-window-fix/ - -//open external links in a new window -function external_new_window() { - for(let c = document.getElementsByTagName("a"), a = 0;a < c.length;a++) { - let b = c[a]; - if(b.getAttribute("href") && b.hostname !== location.hostname) { - b.target = "_blank"; - b.rel = "noopener"; - } - } -} -//open PDF links in a new window -function pdf_new_window () -{ - if (!document.getElementsByTagName) { - return false; - } - let links = document.getElementsByTagName("a"); - for (let eleLink=0; eleLink < links.length; eleLink ++) { - if ((links[eleLink].href.indexOf('.pdf') !== -1)||(links[eleLink].href.indexOf('.doc') !== -1)||(links[eleLink].href.indexOf('.docx') !== -1)) { - links[eleLink].onclick = - function() { - window.open(this.href); - return false; - } - } - } -} - -function apply_rules() { - external_new_window(); - pdf_new_window(); -} - -if (typeof document$ !== "undefined") { - // compatibility with mkdocs-material's instant loading feature - // based on code from https://github.com/timvink/mkdocs-charts-plugin - // Copyright (c) 2021 Tim Vink - MIT License - // fixes [Issue #2](https://github.com/JakubAndrysek/mkdocs-open-in-new-tab/issues/2) - document$.subscribe(function() { - apply_rules(); - }) -} \ No newline at end of file diff --git a/en/site/manage-databases-and-caches/billing-for-platform-services/index.html b/en/site/manage-databases-and-caches/billing-for-platform-services/index.html deleted file mode 100644 index 75a8e84e3..000000000 --- a/en/site/manage-databases-and-caches/billing-for-platform-services/index.html +++ /dev/null @@ -1,3100 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - Billing - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- - - -
- - - - - - -
- - -
- -
- - - - - - - -
-
- - - -
-
-
- - - - -
-
-
- - - -
-
-
- - - -
-
-
- - - -
-
- - - - - - - - - - - - - - - - - - - - -

Billing for Platform Services (Databases and Caches)

-

Any platform services you create within your Choreo Organization will be included in your current Choreo subscription. The quantity included will vary depending on the service plan of the resources you create.

-

A few important considerations:

-
    -
  • Usage is billed hourly. If you create a database that you later remove within the same month, you will only be charged for the hours during which it was active.
    • -
  • Fixed pricing based on service plans. Choreo does not charge extra for network bandwidth usage.
    • -
-
-

Try out the free trial

-

Choreo provides a 7 day free trial for all database types on the 'Hobbyist' service plan (for free tier users).

-
- - - - - - -
-
- - -
- - - -
- - -
- - - -
-
-
- - - - - - - - - - - - - - - - - \ No newline at end of file diff --git a/en/site/manage-databases-and-caches/choreo-managed-caches/index.html b/en/site/manage-databases-and-caches/choreo-managed-caches/index.html deleted file mode 100644 index 8b305f634..000000000 --- a/en/site/manage-databases-and-caches/choreo-managed-caches/index.html +++ /dev/null @@ -1,3408 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - Choreo-Managed Cache - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- - - -
- - - - - - -
- - -
- -
- - - - - - - -
-
- - - -
-
-
- - - - -
-
-
- - - -
-
-
- - - -
-
-
- - - -
-
- - - - - - - - - - - - - - - - - - - - -

Choreo-Managed Cache

-

Fully compatible with legacy Redis® OSS.

-

Choreo-Managed Cache provides fully-managed in-memory NoSQL databases on AWS, Azure, GCP, and Digital Ocean and can be used as a cache, database, streaming engine, or message broker.

-

Create a Choreo-Managed Cache

-

Follow the steps below to create a Choreo-Managed Cache:

-
    -
  1. Sign in to the Choreo Console at https://console.choreo.dev/.
    2. -
  2. In the header, click the Organization list. This opens the organization home page.
    3. -
  3. In the left navigation menu, click Dependencies and then click Databases.
    4. -
  4. Click + Create and select Choreo-Managed Cache as the data store type. Provide a display name for this server and follow the instructions.
    5. -
  5. Select a preferred cloud provider (AWS, Azure, GCP, or Digital Ocean).
      -
    • The cloud provider provisions the compute and storage infrastructure for your data store.
      • -
    • The functionality remains the same across cloud providers, though service plans and costs may differ.
      • -
    -
    6. -
  6. Select a region for your data store.
      -
    • Available regions depend on the selected cloud provider. Choreo currently supports US and EU regions across all providers.
      • -
    -
    7. -
  7. Select a service plan.
      -
    • Service plans vary in terms of dedicated CPU, memory (RAM), and storage space allocated for your data store, as well as high-availability configurations for production use cases.
      • -
    -
    8. -
  8. Click Create.
    9. -
-

Connect to your Choreo-Managed Cache

-

To connect to your Choreo-Managed Cache, follow these guidelines:

-
    -
  • Use any legacy Redis® OSS compatible driver (in any programming language) to connect to your Choreo-Managed Cache.
    • -
  • You can find the connection parameters in the Overview section in the Choreo Console under the relevant database. Note that Choreo-Managed Cache enforces TLS.
    • -
  • Choreo-Managed Cache instances accept traffic from the internet by default. You can restrict access to specific IP addresses and CIDR blocks under Advanced Settings.
    • -
-

High availability and automatic backups

-

The high availability and the automatic backup retention periods for a Choreo-Managed Cache can vary as follows depending on the service plan you select.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Service planHigh availabilityBackup featuresBackup history
HobbyistSingle-node with limited availability.Single backup only for disaster recoveryNone
StartupSingle-node with limited availability.Single backup only for disaster recovery1 day
BusinessTwo-node (primary + standby) with higher availability (automatic failover if the primary node fails).Automatic backups3 days
PremiumThree-node (primary + standby + standby) with highest availability (automatic failover if the primary node fails).Automatic backups13 days
-

In general, service plans are recommended for production scenarios due to the following reasons:

-
    -
  • Provides another physical copy of the data in case of hardware, software, or network failures.
    • -
  • Reduces the data loss window in disaster scenarios.
    • -
  • Ensures quicker restoration with controlled failover in case of failures, as the standby is already installed and running.
    • -
-

Automatic backups

-
    -
  • Choreo runs full backups daily to automatically backup Choreo-Managed Caches and has write-ahead logs (WAL) copied at 5-minute intervals or for every new file generated.
    • -
  • Choreo encrypts all backups at rest.
    • -
  • Choreo automatically handles outages and software failures by replacing broken nodes with new ones that resume correctly from the point of failure. The impact of a failure will depend on the number of available standby nodes in the data store.
    • -
-

Failure recovery

-
    -
  • -

    Minor failures: Choreo automatically handles minor failures such as service process crashes or temporary loss of network access in all plans without requiring significant changes to the service deployment. Choreo automatically restores the service to normal operation once it automatically restarts the crashed process or when it restores the network access.

    -
    • -
  • -

    Severe failures: Failures such as losing a node entirely in case of hardware or severe software problems, require more drastic recovery measures. The monitoring infrastructure automatically detects a failing node when the node starts reporting issues in the self-diagnostics or when it stops communicating. In such cases, the monitoring infrastructure automatically schedules a new replacement node to be created.

    -
      -
    • In the event of a data store failover, the service URI of your service remains the same; only the IP address will change to point to the new primary node.
      • -
    • Hobbyist and Startup plans provide a single node, and in case of failure, a new node starts up, restores its state from the latest available backup, and resumes serving traffic.
      • -
    • As there is just a single/primary node, the caching service becomes unavailable for the duration of the restoration operation. Therefore, all write operations made since the last backup will be lost.
      • -
    -
    • -
-

Limitations

-

Connection limits

-

The number of simultaneous connections in a Choreo-Managed Cache depends on the total available memory on the server instances.

-

You can use the following to estimate:

-
max_number_of_connections = 4 x m
-
- -

Here, m represents the memory in megabytes, where at least 10,000 connections are available, even on the smallest servers. -For example, on a server with 4GB memory (4,096 MB), the simultaneous connections are:

-
4 x 4096 = 16384 // 16k connections
-
- -

This number is estimated by the exact available memory so it can vary between different plans and cloud providers. To see the exact maximum connections allowed, use the * redis-cli and info command as follows:

-
echo "info" | redis-cli -u REDIS_URI | grep maxclients
-
- -

Restricted commands

-

To maintain the stability and security of a managed environment, Choreo restricts certain commands on Choreo-Managed Cache services.

-
-

Support for Lua scripts on Choreo-Managed Cache

-
    -
  • Choreo-Managed Cache has built-in support for running Lua scripts to perform various actions directly on the server. Scripting is typically controlled using the EVAL, EVALSHA, and SCRIPT LOAD commands.
    • -
  • For all newly-created cache instances, EVAL, EVALSHA, and SCRIPT LOAD commands are enabled by default.
    • -
-
-

The following commands are disabled on Choreo:

-
    -
  • bgrewriteaof: Initiates a background append-only file rewrite.
    • -
  • cluster: Manages Caching cluster commands.
    • -
  • command: Provides details about all Caching commands.
    • -
  • debug: Contains sub-commands for debugging Caching.
    • -
  • failover: Manages manual failover of a master to a replica.
    • -
  • migrate: Atomically transfers a key from one caching instance to another.
    • -
  • role: Returns the role of the instance in the context of replication.
    • -
  • slaveof: Makes the server a replica of another instance, or promotes it as master.
    • -
  • acl: Manages caching access control lists.
    • -
  • bgsave: Creates a snapshot of the data set into a dump file.
    • -
  • config: Alters the configuration of a running caching server.
    • -
  • lastsave: Returns the UNIX timestamp of the last successful save to disk.
    • -
  • monitor: Streams back every command processed by the Caching server.
    • -
  • replicaof: Makes the server a replica of another instance.
    • -
  • save: Synchronously saves the dataset to disk.
    • -
  • shutdown: Synchronously saves the dataset to disk and then shuts down the server.
    • -
-

The following eval commands are also disabled:

-
    -
  • eval: Executes a Lua script server-side.
    • -
  • eval_ro: Read-only variant of the eval command.
    • -
  • evalsha: Executes a script cached on the server side by its SHA1 digest.
    • -
  • evalsha_ro: Read-only variant of the evalsha command.
    • -
  • fcall: Calls a Caching function.
    • -
  • fcall_ro: Read-only variant of the fcall command.
    • -
  • function: Manages Caching functions.
    • -
  • script: Manages the script cache.
    • -
- - - - - - -
-
- - -
- - - -
- - -
- - - -
-
-
- - - - - - - - - - - - - - - - - \ No newline at end of file diff --git a/en/site/manage-databases-and-caches/choreo-managed-databases-and-caches/index.html b/en/site/manage-databases-and-caches/choreo-managed-databases-and-caches/index.html deleted file mode 100644 index b55b20f3f..000000000 --- a/en/site/manage-databases-and-caches/choreo-managed-databases-and-caches/index.html +++ /dev/null @@ -1,3184 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - Overview - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- - - -
- - - - - - -
- - -
- -
- - - - - - - -
-
- - - -
-
-
- - - - -
-
-
- - - -
-
-
- - - -
-
-
- - - -
-
- - - - - - - - - - - - - - - - - - - - -

Choreo-Managed Databases, Vector Databases, and Caches

-

Choreo allows you to create PostgreSQL and MySQL databases as well as Choreo-Managed Cache instances on all major cloud providers (AWS, Azure, GCP, and DigitalOcean) as fully Choreo-managed platform services. -These databases and caches can be seamlessly provisioned to offer persistence and caching capabilities for all your Choreo components. Choreo provides various service plans for each type, ranging from smaller instances for development purposes to production-grade databases with automatic backups and high-availability multi-nodes.

-

PostgreSQL on Choreo

-

PostgreSQL (also known as Postgres), is an open-source object-relational database management system. You can create PostgreSQL databases on Choreo as fully Choreo-managed, flexible SQL databases that are ideal for both structured and unstructured data. If you want to perform an efficient vector similarity search, you can create a PostgreSQL vector database.

- -

MySQL on Choreo

-

MySQL is a user-friendly, flexible, open-source relational database management system with a well-established history in the SQL database realm. Choreo allows you to swiftly create fully Choreo-managed MySQL databases, enabling rapid setup and utilization.

- -

Choreo-Managed Cache

-

A fully-managed cache compatible with legacy Redis® OSS. A versatile, in-memory NoSQL database that serves as a cache, database, streaming engine, and message broker. Choreo-managed Cache allows you to have fully-managed instances that can be swiftly provisioned and integrated into your applications within minutes.

- -

- PostgreSQL, MySQL, and Redis® are trademarks and property of their respective owners. All product and service names used in this documentation are for identification purposes only. -

- - - - - - -
-
- - -
- - - -
- - -
- - - -
-
-
- - - - - - - - - - - - - - - - - \ No newline at end of file diff --git a/en/site/manage-databases-and-caches/choreo-managed-mysql-databases/index.html b/en/site/manage-databases-and-caches/choreo-managed-mysql-databases/index.html deleted file mode 100644 index c34feaa44..000000000 --- a/en/site/manage-databases-and-caches/choreo-managed-mysql-databases/index.html +++ /dev/null @@ -1,3328 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - MySQL - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- - - -
- - - - - - -
- - -
- -
- - - - - - - -
-
- - - -
-
-
- - - - -
-
-
- - - -
-
-
- - - -
-
-
- - - -
-
- - - - - - - - - - - - - - - - - - - - -

Choreo-managed MySQL Databases

-

MySQL on Choreo offers fully managed, flexible relational databases on AWS, Azure, GCP, and Digital Ocean.

-

Create a Choreo-managed MySQL database

-

Follow the steps below to create a Choreo-managed MySQL database:

-
    -
  1. From the environment list on the header, located next to the Deployment Tracks list, select your Organization.
    2. -
  2. In the left navigation menu, click Dependencies and then Databases.
    3. -
  3. Click Create and select MySQL as the database type. Provide a display name for this server and follow the instructions.
    4. -
  4. Select your preferred cloud provider from AWS, Azure, GCP, and Digital Ocean.
    5. -
  5. Choreo uses the cloud provider to provision the compute and storage infrastructure for your database.
    6. -
  6. There is no functional difference between databases created on different cloud providers, apart from changes to service plans (and associated costs).
    7. -
  7. Choose the region for your database.
    8. -
  8. Available regions will depend on the selected cloud provider. Choreo currently supports US and EU regions across all providers.
    9. -
  9. Select the service plan.
    10. -
  10. Service plans vary in the dedicated CPU, memory (RAM), storage space allocated for your database, the backup retention periods, and high-availability configurations for production use cases.
    11. -
-

Connect to your Choreo-managed MySQL database

-

To connect to your Choreo-managed MySQL database, consider the following guidelines:

-
    -
  • You can use any MySQL driver, ORM, or supported generic SQL library (may depend on the programming language) to connect to the database.
    • -
  • You can find the connection parameters in the Overview section in the Choreo Console under the relevant database.
    • -
  • MySQL databases accept traffic from the internet by default. You can restrict access to specific IP addresses and CIDR blocks under Advanced Settings.
    • -
-

High Availability and Automatic Backups

-

The high availability characteristics and the automatic backup retention periods for Choreo-managed MySQL databases vary based on your service plan as explained below:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Service PlanHigh AvailabilityBackup Retention Time
HobbyistSingle-node with limited availabilityNone
StartupSingle-node with limited availability2 days
BusinessTwo-node (primary + standby) with higher availability14 days
PremiumThree-node (primary + standby + standby) with highest availability30 days
-

In general, we recommend service plans for production scenarios for multiple reasons: -- Provides another physical copy of the data in case of hardware, software, or network failures. -- Typically reduces the data loss window in disaster scenarios. -- Provides a quicker time to restore with a controlled failover in case of failures, as the standby is already installed and running.

-

Automatic Backups

-
    -
  • -

    Choreo runs full backups daily to automatically back up Choreo-managed MySQL databases and record binary logs continuously. -Choreo encrypts all backups at rest.

    -
    • -
  • -

    Choreo automatically handles outages and software failures by replacing broken nodes with new ones that resume correctly from the point of failure. The impact of a failure will depend on the number of available standby nodes in the database.

    -
    • -
-

Connection Limits

-

The maximum number of simultaneous connections to MySQL databases is fixed for each service plan and depends on how much RAM your service plan offers.

-
-

Note

-

An extra_connection with a value of 1 is added for system processes for all MySQL databases, regardless of the service plan.

-
-

For plans under 4 GiB RAM

-

For plans under 4 GiB of RAM, the number of allowed connections is 75 per GiB:

-
max_connections = 75 x RAM + extra_connection
-
- -

For plans with over 4 GiB RAM:

-

For plans with 4 GiB or more RAM, the number of allowed connections is 100 per GiB:

-
max_connections = 100 x RAM + extra_connection
-
- - - - - - -
-
- - -
- - - -
- - -
- - - -
-
-
- - - - - - - - - - - - - - - - - \ No newline at end of file diff --git a/en/site/manage-databases-and-caches/choreo-managed-postgresql-databases/index.html b/en/site/manage-databases-and-caches/choreo-managed-postgresql-databases/index.html deleted file mode 100644 index ee7792fb4..000000000 --- a/en/site/manage-databases-and-caches/choreo-managed-postgresql-databases/index.html +++ /dev/null @@ -1,3356 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - PostgreSQL - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- - - -
- - - - - - -
- - -
- -
- - - - - - - -
-
- - - -
-
-
- - - - -
-
-
- - - -
-
-
- - - -
-
-
- - - -
-
- - - - - - - - - - - - - - - - - - - - -

Choreo-Managed PostgreSQL Databases and Vector Databases

-

PostgreSQL on Choreo offers fully Choreo-managed, efficient object-relational databases on AWS, Azure, GCP, and Digital Ocean. Additionally, Choreo allows you to create fully-managed PostgreSQL vector databases if you want to perform efficient vector similarity search.

-

Create a Choreo-managed PostgreSQL database

-

Follow the steps below to create a Choreo-managed PostgreSQL database:

-
    -
  1. Sign in to the Choreo Console at https://console.choreo.dev/.
    2. -
  2. In the header, click the Organization list. This opens the organization home page.
    3. -
  3. In the left navigation menu, click Dependencies and then Databases.
    4. -
  4. Click Create and select PostgreSQL as the database type. Provide a display name for this server and follow the instructions.
    5. -
  5. Select your preferred cloud provider from AWS, Azure, GCP, or Digital Ocean.
      -
    • The cloud provider is used to provision the compute and storage infrastructure for your database.
      • -
    • There is no functional difference between databases created on different cloud providers, apart from changes to service plans (and associated costs).
      • -
    -
    6. -
  6. Choose the region for your database.
    7. -
  7. Available regions will depend on the selected cloud provider. Choreo currently supports US and EU regions across all providers.
    8. -
  8. Select the service plan.
    9. -
  9. Service plans vary in the dedicated CPU, memory (RAM), storage space allocated for your database, the backup retention periods, and high-availability configurations for production use cases.
    10. -
-

Create a Choreo-managed PostgreSQL vector database

-

Follow the steps below to create a Choreo-managed PostgreSQL vector database:

-
    -
  1. Sign in to the Choreo Console at https://console.choreo.dev/.
    2. -
  2. In the header, click the Organization list. This opens the organization home page.
    3. -
  3. In the left navigation menu, click Dependencies and then Vector Databases.
    4. -
  4. Follow steps 4 onwards in the Create a Choreo-managed PostgreSQL database section.
    5. -
-

Connecting to your Choreo-managed PostgreSQL database

-

To connect to your Choreo-managed PostgreSQL database, consider the following guidelines:

-
    -
  • You can use any PostgreSQL driver, ORM, or supported generic SQL library (may depend on the programming language) to connect to the database.
    • -
  • The connection parameters can be found in the Overview section in the Choreo Console under the relevant database.
    • -
  • PostgreSQL databases accept traffic from the internet by default. You can restrict access to specific IP addresses and CIDR blocks under Advanced Settings.
    • -
-

High Availability and Automatic Backups

-

The high availability characteristics and the automatic backup retention periods for Choreo-managed PostgreSQL databases vary based on the selected service plan as shown below.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Service PlanHigh AvailabilityBackup Retention Time
HobbyistSingle-node with limited availabilityNone
StartupSingle-node with limited availability2 days
BusinessTwo-node (primary + standby) with higher availability14 days
PremiumThree-node (primary + standby + standby) with highest availability30 days
-

Service plans with standby nodes are generally recommended for production scenarios for multiple reasons: -- Provides another physical copy of the data in case of hardware, software, or network failures. -- Typically reduces the data loss window in disaster scenarios. -- Provides a quicker time to restore with a controlled failover in case of failures, as the standby is already installed and running.

-

Automatic Backups

-
    -
  • -

    Choreo runs full backups daily to automatically back up Choreo-managed PostgreSQL databases and copies the write-ahead logs (WAL) at 5-minute intervals or for every new file generated. -Choreo encrypts all backups at rest.

    -
    • -
  • -

    Choreo automatically handles outages and software failures by replacing broken nodes with new ones that resume correctly from the point of failure. The impact of a failure will depend on the number of available standby nodes in the database.

    -
    • -
-

Failure Recovery

-
    -
  • -

    Minor failures: Choreo automatically handles minor failures such as service process crashes or temporary loss of network access in all plans without requiring significant changes to the service deployment. Choreo automatically restores the service to normal operation once Choreo automatically restarts the crashed process or when Choreo restores the network access.

    -
    • -
  • -

    Severe failures: To handle severe failures such as losing a node entirely in case of hardware or severe software problems, requires more drastic recovery measures. The monitoring infrastructure automatically detects a failing node, both when the node starts reporting issues in the self-diagnostics or when it stops communicating. In such cases, the monitoring infrastructure automatically schedules a new replacement node to be created.

    -
    -
      -
    • In the event of database failover, the Service URI of your service remains the same; only the IP address will change to point to the new primary node.
      • -
    • Hobbyist and Startup plan provide a single node, and in case of failure, a new node starts up, restores its state from the latest available backup, and resumes serving traffic. -In this plan, as there is just a single node providing the service, the service will become unavailable for the duration of the restoration. In addition, any write operations made since the backup of the latest WAL file will be lost. Typically, this time window is limited to either five minutes of time or one WAL file.
      • -
    -
    -
    • -
-

Connection limits

-

The following connection limits apply to Choreo-managed PostgreSQL databases based on the selected service plan.

- - - - - - - - - - - - - - - - - - - - - - - - - -
Service PlanMax Connections
Hobbyist25
Startup/Business/Premium-4100
Business-16400
Premium-8200
- - - - - - -
-
- - -
- - - -
- - -
- - - -
-
-
- - - - - - - - - - - - - - - - - \ No newline at end of file diff --git a/en/site/manage-databases-and-caches/choreo-managed-redis-datastores/index.html b/en/site/manage-databases-and-caches/choreo-managed-redis-datastores/index.html deleted file mode 100644 index 8efb13a5d..000000000 --- a/en/site/manage-databases-and-caches/choreo-managed-redis-datastores/index.html +++ /dev/null @@ -1,15 +0,0 @@ - - - - - - Redirecting... - - - - - - -Redirecting... - - diff --git a/en/site/manage/api-management/index.html b/en/site/manage/api-management/index.html deleted file mode 100644 index b35a70318..000000000 --- a/en/site/manage/api-management/index.html +++ /dev/null @@ -1,15 +0,0 @@ - - - - - - Redirecting... - - - - - - -Redirecting... - - diff --git a/en/site/manage/api-rate-limiting/index.html b/en/site/manage/api-rate-limiting/index.html deleted file mode 100644 index 5a52bcf08..000000000 --- a/en/site/manage/api-rate-limiting/index.html +++ /dev/null @@ -1,15 +0,0 @@ - - - - - - Redirecting... - - - - - - -Redirecting... - - diff --git a/en/site/manage/api-security/pass-end-user-attributes-to-the-backend/index.html b/en/site/manage/api-security/pass-end-user-attributes-to-the-backend/index.html deleted file mode 100644 index 5a52bcf08..000000000 --- a/en/site/manage/api-security/pass-end-user-attributes-to-the-backend/index.html +++ /dev/null @@ -1,15 +0,0 @@ - - - - - - Redirecting... - - - - - - -Redirecting... - - diff --git a/en/site/manage/lifecycle/index.html b/en/site/manage/lifecycle/index.html deleted file mode 100644 index b35a70318..000000000 --- a/en/site/manage/lifecycle/index.html +++ /dev/null @@ -1,15 +0,0 @@ - - - - - - Redirecting... - - - - - - -Redirecting... - - diff --git a/en/site/manual-triggers/index.html b/en/site/manual-triggers/index.html deleted file mode 100644 index 0ca9dfa19..000000000 --- a/en/site/manual-triggers/index.html +++ /dev/null @@ -1,15 +0,0 @@ - - - - - - Redirecting... - - - - - - -Redirecting... - - diff --git a/en/site/marketplace/index.html b/en/site/marketplace/index.html deleted file mode 100644 index 1bdd86271..000000000 --- a/en/site/marketplace/index.html +++ /dev/null @@ -1,15 +0,0 @@ - - - - - - Redirecting... - - - - - - -Redirecting... - - diff --git a/en/site/monitoring-and-insights/alerts/configure-alerts/index.html b/en/site/monitoring-and-insights/alerts/configure-alerts/index.html deleted file mode 100644 index bfb8f2413..000000000 --- a/en/site/monitoring-and-insights/alerts/configure-alerts/index.html +++ /dev/null @@ -1,3240 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - Configure Alerts - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- - - -
- - - - - - -
- - -
- -
- - - - - - - -
-
- - - -
-
-
- - - - -
-
-
- - - -
-
-
- - - -
-
-
- - - -
-
- - - - - - - - - - - - - - - - - - - - -

Configure Alerts

-

This section explains how you can configure alerts for your API manager deployments. Setting up alerts allows you to proactively monitor your API ecosystem and take corrective measures when necessary.

-

You can configure alerts for each environment within your organization. You can add, modify, or delete alerts per API. Optionally, you can specify a list of emails for each alert configuration.

-

Alerts are subject to a suppression policy to prevent duplicate notifications within a specific time frame. By default, a 10-minute suppression window is applied, and this is not configurable. The suppression policy is specific to each alert configuration.

-
-

Info

-
    -
  • You can configure a maximum of 20 alerts per organization, environment, and tenant combination.
    • -
  • Adding email addresses to an alert configuration is optional. If necessary, you can add a maximum of 5 email addresses per alert.
    • -
-
-

Alerts can be categorized as either latency alerts or traffic alerts.

-

Latency alerts

-

Latency alerts notify you if the response latency of an API exceeds a predefined threshold. This is useful for APIs that need to meet specific SLAs and for proactively identifying slow APIs.

-

To configure a new latency alert, follow the steps given below:

-
    -
  1. Sign in to the Choreo Console.
    2. -
  2. Ensure you are in the correct organization where you have a project with the API to configure a latency alert.
    3. -
  3. In the Choreo Console left navigation menu, click Usage Insights.
    4. -
  4. In the left navigation menu on the Usage Insights page, click Alerts.
    5. -
  5. Click the Environment list and select the required environment.
    6. -
  6. -

    Click Alert Configuration.

    -

    Configure alerts

    -

    This opens the Alert Configuration pane with the Latency tab open by default.

    -
    7. -
  7. -

    In the API Name field, select the API for which you want to configure the alert.

    -
    -

    Info

    -

    Only the APIs that you have invoked at least once are listed here. For other APIs, you need to give the API name in the required format as instructed in the UI.

    -
    -
    8. -
  8. -

    In the Metric field, select the required metric against which you want to evaluate the alert configuration.

    -
    -

    Tip

    -

    The list includes all available options. If there are multiple metrics, you can select the required metric. If there is only one metric to choose, that metric is selected by default, and the field is disabled.

    -
    -
    9. -
  9. -

    In the Latency field, specify the threshold in milliseconds.

    -
    -

    Info

    -

    When the 95th percentile of the selected metric exceeds the threshold provided here, alerts are triggered.

    -
    -
    10. -
  10. -

    In the Emails field, specify the list of emails that should be notified when the alert is added.

    -
    11. -
  11. -

    Click + Add.

    -
    12. -
-

Once an alert is successfully added, the alert configuration is listed in the Alert Configuration pane. Each configuration can be edited and removed via this pane.

-

Traffic alerts

-

Traffic alerts notify you when the request count of an API exceeds a predefined threshold. This is useful for managing APIs with backend traffic limits or monetized backends that require proactive scaling based on incoming traffic.

-

To configure a new traffic alert, follow the steps below:

-
    -
  1. Sign in to the Choreo Console.
    2. -
  2. Ensure you are in the correct organization where you have a project with the API to configure a latency alert.
    3. -
  3. In the Choreo Console left navigation menu, click Usage Insights.
    4. -
  4. In the left navigation menu on the Usage Insights page, click Alerts.
    5. -
  5. Click the Environment list and select the required environment.
    6. -
  6. Click Alert Configuration. This opens the Alert Configuration pane.
    7. -
  7. Click the Traffic tab.
    8. -
  8. -

    In the API Name field, select the API for which you want to configure the alert.

    -
    -

    Info

    -

    Only the APIs that you have invoked at least once are listed here. For other APIs, you need to give the API name in the required format as instructed in the UI.

    -
    -
    9. -
  9. -

    In the Metric field, select the required metric against which you want to evaluate the alert configuration.

    -
    -

    Tip

    -

    The list includes all available options. If there are multiple metrics, you can select the required metric. If there is only one metric to choose, that metric is selected by default, and the field is disabled.

    -
    -
    10. -
  10. -

    In the Threshold field, specify the threshold number of requests per minute.

    -
    11. -
  11. -

    If required, specify the list of emails that should be notified when the alert is generated in the Emails field.

    -
    12. -
  12. -

    Click Add.

    -
    13. -
-

Once an alert is successfully added, the alert configuration is listed in the Alert Configuration pane. Each configuration can be edited and removed via this pane.

- - - - - - -
-
- - -
- - - -
- - -
- - - -
-
-
- - - - - - - - - - - - - - - - - \ No newline at end of file diff --git a/en/site/monitoring-and-insights/delivery-insights/configure-dora-metrics/index.html b/en/site/monitoring-and-insights/delivery-insights/configure-dora-metrics/index.html deleted file mode 100644 index b7b5056f3..000000000 --- a/en/site/monitoring-and-insights/delivery-insights/configure-dora-metrics/index.html +++ /dev/null @@ -1,3326 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - Configure DORA Metrics - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- - - -
- - - - - - -
- - -
- -
- - - - - - - -
-
- - - -
-
-
- - - - -
-
-
- - - -
-
-
- - - -
-
-
- - - -
-
- - - - - - - - - - - - - - - - - - - - -

Configure CIO Dashboard

-

CIO dashboard

-

You can view DORA metrics in Choreo to use as KPIs to measure your organization's DevOps team's performance. Choreo enables this feature by default for all organizations. DORA includes the following four key metrics that are regarded as the most important metrics to indicate team performance:

-
    -
  • Deployment Frequency: How often an organization successfully releases to production
    • -
  • Lead Time for Changes: The amount of time it takes a commit to get into production
    • -
  • Change Failure Rate: The percentage of deployments causing a failure in production
    • -
  • Time to Restore Service: How long it takes an organization to recover from a failure in production
    • -
-

Choreo enables two DORA metrics by default; deployment frequency and lead time for change.

-

Configure the CIO Dashboard with all metrics

-

To configure the CIO dashboard by enabling the other two metrics, follow the steps below:

-
    -
  1. Sign in to Choreo using your Google, GitHub, or Microsoft account.
    2. -
  2. On the left navigation menu, click Delivery Insights.
    3. -
  3. Click on the DORA Metrics tab.
    4. -
  4. Scroll to the bottom of the dashboard and click Configure.
    5. -
  5. Select your incident management system. Currently, Choreo only supports GitHub.
    6. -
-

Configuring GitHub as the incident management system

-

Configure

-

To configure GitHub as the incident management system, follow the steps below:

-

Step 1: Authorize

-

Authorize

-

First, let's authorize Choreo to access the repositories used to record incidents.

-

On the Add Integration page, select GitHub and click Authorize with GitHub.

-

Once the authorization process is complete, you can start configuring the GitHub repository.

-

Step 2: Configure

-

Configure

-

By default, Choreo collects incident details(issues) from all repositories containing Choreo components. However, you can configure a GitHub account and a GitHub repository to allow Choreo to read issues from a specific repository, and then click Next.

- - - - - - - - - - - - - - - - - - - - - - - - - -
FieldDescriptionValue
Data PlaneChoreo collects incident details by running a scheduled job which invokes the GitHub API periodically. This job runs on the user's data plane. This configuration allows users to specify a preferred data plane to run the job, especially when they have multiple data planes.Select a preferred data plane from the Data Plane list.
GitHub AccountThe GitHub account you have your repositories in.Select your GitHub account that includes the repository used for incident collection.
GitHub RepositoryBy default, Choreo will collect incident details(issues) from all repositories that already have Choreo components.
-

Step 3: Filter label

-

Filter Label

-

The filter label allows Choreo to scrape issues associated with that label.

-
    -
  • -

    Incident Label: The label Choreo uses to identify incidents. For example, Type/Incident.

    -
    • -
  • -

    Invalid incident label(Optional): Choreo will not scrape issues with this label and will proceed to skip these issues. For example, Resolution/Invalid. You can use this label when you want to ignore issues. For example, closing an issue after identifying that it doesn't qualify as an incident issue as it was due to a user error.

    -
    • -
-

Once you configure the labels, click Save.

-

Choreo will enable incident data publishing in the background once you save. Once completed, DORA metric charts will appear in the CIO dashboard for Mean Time To Recover and Change Failure Rate. If there are any issues in the configuration, the configure banner will reappear, and the user can proceed to reconfigure.

-

Step 4: Enrich incident tickets with deployment information

-

Choreo extracts deployment information from the relevant incident and generates DORA metrics that help you analyze the deployment statistics related to the incidents. Therefore, you must manually update the GitHub issue with the relevant deployment-related information. Follow the steps below to add the deployment information to the GitHub issue.

-

Get deployment details

-
    -
  1. On the Choreo Console header, select the project and the component for which the incident was reported.
    2. -
  2. On the left navigation menu, click Deploy.
    3. -
  3. On the Production Environment card, click Deployment History.
    4. -
  4. -

    On the right-hand side panel, select the relevant deployment, and click Release details to copy the deployment details to the clipboard.

    -

    Copy to clipboard

    -
    5. -
-

Add deployment information to the GitHub issue

-
    -
  1. Edit the GitHub issue to add the deployment information.
    2. -
  2. Paste the deployment information you copied (in step 4 under the section Get deployment details) at the end of the issue body.
    3. -
  3. Click Save.
    4. -
-

That's it! You have successfully configured your CIO dashboard to include the DORA metrics.

-
-

Note

-

The CIO Dashboard is expected to reflect the latest statistics within approximately 30 minutes.

-
-

Edit configurations

-

Edit configurations

-

You can edit or override the configurations you made via the edit option in the dashboard.

- - - - - - -
-
- - -
- - - -
- - -
- - - -
-
-
- - - - - - - - - - - - - - - - - \ No newline at end of file diff --git a/en/site/monitoring-and-insights/delivery-insights/view-dora-metrics/index.html b/en/site/monitoring-and-insights/delivery-insights/view-dora-metrics/index.html deleted file mode 100644 index 6d486c9e5..000000000 --- a/en/site/monitoring-and-insights/delivery-insights/view-dora-metrics/index.html +++ /dev/null @@ -1,3424 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - View DORA Metrics - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- - - -
- - - - - - -
- - -
- -
- - - - - - - -
-
- - - -
-
-
- - - - -
-
-
- - - -
-
-
- - - -
-
-
- - - -
-
- - - - - - - - - - - - - - - - - - - - -

View DORA metrics

-

DORA metrics comprise four key metrics. Let's explore what each metric represents in Choreo. Choreo displays a summary and graphical representation of each metric.

-

Snapshot view

-

DORA metric summary

-

The snapshot view includes four tiles on the top of the dashboard, summarizing DORA metrics for the entire time period you select. The snapshot view categorizes each metric into four performance levels: elite, high, medium, and low. The categorization is based on the 2020 DORA metric report.

-

DORA matrix

-

Time series view

-

The time series view provides a graphical representation of how the statistics have changed over a period of time. You can use this view to analyze team performance and identify trends.

-

Time Series View

-

Deployment frequency

-

DORA team definition: The frequency at which an organization successfully releases to production.

-

In Choreo, this translates to the number of times an organization deploys a component to the production environment. Choreo does not count the deployment done to the development or other lower environments.

-

Snapshot view

-

Deployment Frequency Snapshot

-

The snapshot view of the Deployment Frequency metric shows the deployment frequency for all components within the selected organization. The frequency is dynamically determined and rounded to the nearest measurement. For example, if there is more than one deployment daily, the deployment frequency is measured in deployments per day. If the deployment frequency is less, it is measured in a higher granularity. For example, deployments per week.

-

A lower deployment frequency indicates that your organizational efficiency is low and that you need to evaluate and improve the processes to encourage frequent releases.

-

Choreo also displays the total number of deployments for the selected time range and the percentage increase or decrease compared to the previous time range.

-

Time series view

-

Deployment Frequency time series view

-

The time series view for the Deployment Frequency metric visualizes the deployment count as a bar chart for the selected time period. Deployment count is aggregated based on the ‘view by’ selector. Hovering over each bar shows the counts for the aggregated period. -Using this chart, organizations can identify deployment patterns, such as days of the week/months of the year where more deployments are likely to happen (near quarterly release days) and periods with fewer deployments. Decision-makers can then take steps to investigate and improve performance. -This chart displays the pattern before and after a process change so you can use it to evaluate the team's performance after a significant process change.

-

Lead Time for Change

-

DORA team definition: The time it takes for a commit to reach production.

-

In Choreo, this translates into the time between committing and promoting a deployment to production. Although this approach may overlook any commits you push to production between two commits, it effectively assesses the efficiency of the review, approval, and CI/CD processes. Therefore, focusing on the production commits is adequate. If a team commits locally for extended periods without deploying to production, this gets reflected in the Deployment Frequency charts.

-

Snapshot view

-

Lead Time For Change Frequency Snapshot

-

The snapshot view of this metric displays the 95th percentile of the lead time for the selected time period. 95th percentile serves as a better representation as it filters out large outliers that can taint the average value. Lower lead times for change suggest that your organization has efficient processes for change review, approval, and CI/CD, while longer times suggest that the process needs to improve. Organizations can also use the categorization label to determine their standpoint on global standards.

-

Additionally, Choreo also displays the percentage increase or decrease compared to the last time period.

-

Time series view

-

Lead Time For Change Frequency Time Series View

-

The time series view of this metric visualizes the lead time as a bar chart for the selected time period. The time is summed based on the ‘view by’ selector. To handle outliers, the y-axis employs a log scale that represents values read dynamically. Hovering over each bar displays the actual counts for the aggregated period. -Using this chart, organizations can identify trends in their release process. For example, organizations can identify the time of the year when lead time rises, such as summer break. Also, organizations can use this to benchmark and evaluate new process changes. For example, if you introduced a process to include peer programming and reviewing, this chart can be used to evaluate its effect on the lead time and provide leadership with factual information to proceed further.

-

Change failure rate

-

The DORA team definition: The percentage of deployments causing a failure in production.

-

In Choreo, this translates to the ratio of deployments causing production failures to the total number of deployments. If there is at least one incident reported against a deployment, Choreo considers that deployment as a failed deployment in production. Any deployment-time failures are not counted as production failures because such failures don't impact the end user. For this metric to be accurate, the organization is expected to open incidents adhering to the proper format as it is crucial for Choreo to identify production failures.

-

Snapshot view

-

Change Failure Rate Snapshot

-

The snapshot view of this metric visualizes the change failure rate as a percentage for the selected time period. This will be the absolute percentage for the entire time period. When deciding on the time, the time of deployment is considered instead of the incident reported time. For example, the change failure rate for January 2023 will reflect the following: - - All deployments that happened within January. - - Any incidents that were reported at any time (in or after January) against the January deployments.

-

This view helps leadership assess the quality of deliverables and identify areas for improvement. Higher rates suggest that the organization needs to improve its processes to bring in more quality assurance aspects such as improved code coverage and end-to-end test coverage.

-

Additionally, Choreo also shows the percentage increase or decrease compared to the previous time period.

-

Time series view

-

Change Failure Rate Time Series

-

The time series view of this metric displays it as a line chart with data points corresponding to the granularity selected by the ‘view by’ selector. The absolute percentage is shown for each granularity. Hovering over the line chart displays the actual counts for the aggregated period. -This chart helps leadership identify timely trends in product quality aspects. For example, this view displays the months of the year where the failure rate is high (for example, close to quarterly release/announcement dates). Also, you can use this to measure the effectiveness of changes introduced to improve quality. For example, if the organization introduced an end-to-end test pipeline integration to the PR approval process, they can use this view to factually observe the timely impact of that change and determine how it decreases the failure rate.

-

Mean Time to Recover(MTTR)

-

The DORA team definition: The time it takes for an organization to recover from a production failure.

-

In Choreo, this measures the time from identifying a production incident to resolving it. This metric reflects the responsiveness and agility of incident management teams.

-

Choreo depends on the open and close times of incidents to gather the relevant information. Therefore, for the dashboards to be accurate, organizations must follow process guidelines to update and close incident tickets efficiently in their incident management system.

-

Snapshot view

-

Mean Time to Recovery Snapshot

-

The snapshot view for this metric displays the mean recovery time for the selected time period. Choreo dynamically adjusts the time unit to measure this metric for better readability. -This chart helps organizations evaluate the response time and agility of their incident handling teams, which in turn is an indication of stability. Higher MTTR means the leadership should look at new ways of improving the efficiency and agility of the teams handling incidents.

-

Time series view

-

Mean Time to Recovery Time Series

-

The time series view of this metric shows how the mean time to recovery changes over time on a granularity based on the ‘view by’ selector. Each time the granularity mean would be used as the aggregation factor. Hovering over the line chart displays the actual counts for the aggregated period. -This view helps leadership understand timely trends on mean time to recovery, such as higher values during holiday periods when there is less staff. Also, you can use this measurement to evaluate the effectiveness of process changes such as introducing an incident response plan. The trend view clearly shows the before and after statistics and the effectiveness of the process change.

- - - - - - -
-
- - -
- - - -
- - -
- - - -
-
-
- - - - - - - - - - - - - - - - - \ No newline at end of file diff --git a/en/site/monitoring-and-insights/engineering-insights/configure-cio-dashboard/index.html b/en/site/monitoring-and-insights/engineering-insights/configure-cio-dashboard/index.html deleted file mode 100644 index 107f383f6..000000000 --- a/en/site/monitoring-and-insights/engineering-insights/configure-cio-dashboard/index.html +++ /dev/null @@ -1,15 +0,0 @@ - - - - - - Redirecting... - - - - - - -Redirecting... - - diff --git a/en/site/monitoring-and-insights/engineering-insights/view-dora-metrics/index.html b/en/site/monitoring-and-insights/engineering-insights/view-dora-metrics/index.html deleted file mode 100644 index df6441bd5..000000000 --- a/en/site/monitoring-and-insights/engineering-insights/view-dora-metrics/index.html +++ /dev/null @@ -1,15 +0,0 @@ - - - - - - Redirecting... - - - - - - -Redirecting... - - diff --git a/en/site/monitoring-and-insights/generate-custom-reports/index.html b/en/site/monitoring-and-insights/generate-custom-reports/index.html deleted file mode 100644 index 11bfc29d9..000000000 --- a/en/site/monitoring-and-insights/generate-custom-reports/index.html +++ /dev/null @@ -1,3221 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - Generate Custom Reports - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- - - -
- - - - - - -
- - -
- -
- - - - - - - -
-
- - - -
-
-
- - - - -
-
-
- - - -
-
-
- - - -
-
-
- - - -
-
- - - - - - - - - - - - - - - - - - - - -

Generate Custom Reports

-

Choreo insights allow you to generate custom reports to view the information that is important to you to make timely decisions for the betterment of your business. With custom reports, you can generate reports for a set of metrics of your choice and aggregate results by specific fields. Once generated, the metrics can be filtered out using any selected group-by filters. Custom reports support three visualizations: overtime charts, pie charts, and tables.

-

Metrics

-

Choreo Insights allow you to retrieve data for the following metrics:

-
    -
  • Successful Hit Count
    • -
  • Response Cache Hits
    • -
  • Request Mediation Latency
    • -
  • Response Mediation Latency
    • -
  • Backend Latency
    • -
  • Total Latency
    • -
  • API Errors
    • -
  • Target Errors
    • -
-

Group-by

-

Group-by fields specify how to group the metric data. e.g., You can select Successful Hit Count in the Metrics field and API Name under Group-by to retrieve the successful hit count grouped by the API name.

-

Choreo Insights allow you to group metric data by the following fields:

-
    -
  • API Name
    • -
  • API Version
    • -
  • API Resource Template
    • -
  • API Method
    • -
  • API Creator
    • -
  • Application
    • -
  • Application Owner
    • -
  • Destination
    • -
  • User Agent
    • -
  • Platform
    • -
-

To generate a custom report, follow the steps below:

-
    -
  1. -

    In the left navigation menu, click Custom Reports.

    -

    Select Custom Reports

    -
    2. -
  2. -

    Select metric(s) from the Metrics drop-down selector.

    -

    Generate report

    -
    3. -
  3. -

    Select a minimum of 1 and a maximum of 3 group-by field(s) from the Group By drop down selector.

    -
    4. -
  4. -

    Set the order of the group-by filters by drag and drop to determine the grouping order of the selected metric(s).

    -
    5. -
  5. -

    Once you determine the order of the group-by fields, you can set values for each group-by field from the respective dropdown.

    -

    Group by field selection

    -
    6. -
  6. -

    Click Generate.

    -

    Generate

    -
    7. -
-

Download Reports

-

Choreo Insights allow you to download report data related to each chart as a PDF or a CSV file.

-

To do this, click the Download icon on the top right of the relevant chart and select the required file format. - Download Report

- - - - - - -
-
- - -
- - - -
- - -
- - - -
-
-
- - - - - - - - - - - - - - - - - \ No newline at end of file diff --git a/en/site/monitoring-and-insights/insights-overview/index.html b/en/site/monitoring-and-insights/insights-overview/index.html deleted file mode 100644 index 91fd7ec4d..000000000 --- a/en/site/monitoring-and-insights/insights-overview/index.html +++ /dev/null @@ -1,3632 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - Insights Overview - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- - - -
- - - - - - -
- - -
- -
- - - - - - - -
-
- - - -
-
-
- - - - -
-
-
- - - -
-
-
- - - -
-
-
- - - -
-
- - - - - - - - - - - - - - - - - - - - -

Insights Overview

-

Choreo provides comprehensive insights into APIs created within both the on-premises API Manager and the Choreo platform. Choreo insights provide a range of metrics, including API traffic, error rates, and latency, allowing you to monitor and optimize API performance effectively.

-

With Choreo insights, you can:

-
    -
  • Analyze API traffic: Monitor the volume of requests and responses to understand usage patterns.
    • -
  • Track errors: Identify and analyze errors to improve API reliability.
    • -
  • Monitor latency: Measure and optimize the response times of your APIs.
    • -
  • Generate reports: Generate detailed reports to keep stakeholders informed and support data-driven decision-making.
    • -
  • Configure alerts: Set up alerts for specific events or thresholds to proactively manage API performance.
    • -
  • Obtain granular insights: Obtain detailed information on a per-application, per-API, and per-user basis for more targeted analysis.
    • -
  • Drill down into data: Dive deeper into data to perform root cause analysis.
    • -
-

By leveraging these insights, businesses can make informed decisions to enhance their API strategies and drive their digital transformation initiatives forward.

-

View insights

-

To view usage insights, go to the Choreo Console and click Usage Insights in the left navigation menu.

-

If you are viewing insights on the Choreo platform at the organization level, note the following:

-
    -
  • Permission-based access: Signed-in users can only view insights for components or projects that they have permission to access.
    • -
  • Data exclusion: Insights exclude data from components you cannot access and the data related to deleted components.
    • -
  • Comprehensive view permission: To view insights for all components, including deleted ones, across the organization regardless of project visibility, you must have the View Organization Insights permission under OBSERVABILITY-MANAGEMENT with the mapping level defined at the Organization level.
    • -
  • Admin role: Users with the admin role have the View Organization Insights permission by default and can view organization-wide insights.
    • -
  • Configuring permissions: For detailed steps on configuring permissions, see Control Access in the Choreo Console.
    • -
-

By ensuring proper permissions are set, organizations can manage access to insights effectively while maintaining data security and relevance.

-

Analyze statistics

-

Once you access the Usage Insights page, you can access the following subpages.

-

Overview

-

The Overview page gives you a quick overview of the system status.

-

Overview

-

The information displayed is as follows:

-
    -
  • -

    Total Traffic

    -

    Total traffic

    -

    This widget displays the total traffic of the selected environment received during a given time interval. Both successful requests and failed requests are displayed. To investigate further, you can click the arrow icon on the bottom right corner of the widget to open the Traffic page.

    -
    • -
  • -

    Error Request Count

    -

    Error request count

    -

    This widget displays the total number of requests that have resulted in errors in your selected environment during the selected time range.

    -
    • -
  • -

    Average Error Rate

    -

    Average error rate

    -

    This widget displays the average error rate (i.e., error count/total request count) of the selected environment for a given time interval. You can use this widget as an indicator to understand the health of the system. If the error rate is high, you can investigate further by clicking the arrow on the bottom right of the widget and opening the Errors page.

    -
    • -
  • -

    95th Percentile Latency

    -

    95th percentile latency

    -

    This widget displays the 95th percentile of all API latencies in your selected environment for the given time interval. You can use this widget to know whether the complete system operates under given SLAs. This metric provides the first indication of slow APIs. To investigate further, you can click the arrow on the bottom right of the widget to open the Latency page where you can further analyze the latency.

    -
    • -
  • -

    API Request Summary

    -

    API request summary

    -

    This chart displays the total successful requests, the total requests that have resulted in errors, and the latency in a timeline. The y-axis on the left displays the request count and the error count. The x-axis shows time, and the y-axis on the right shows the latency in milliseconds. The granularity of the data points is decided based on the time range you have selected. The tooltip provides the exact value of all three metrics accurately.

    -
    • -
-

Traffic

-

The Traffic page shows information related to the traffic that goes through your API management deployments. This includes API usage, application usage, resource usage, etc. You can use this page to investigate the usage of APIs and applications, traffic patterns, etc.

-

Traffic

-

You can filter the information displayed in the widgets as follows:

- - - - - - - - - - - - - - - - - -
Filtering OptionDescription
By APIIn the API field, you can select one or more APIs for which you want to view analytics. All is selected by default. Once you select an API, you can further filter by a specific application that uses the selected API via the Application field described below.
By ApplicationIn the Application field, you can select the applications for which you want to view analytics. All is selected by default. The available applications are all the applications that have subscribed to one or more of the APIs you selected in the API field.
-

You can view the following information for the APIs you have selected using the above filtering criteria:

-
    -
  • -

    API Usage Over Time

    -

    This timeline shows the count of API hits for the APIs for the filtered APIs. If multiple APIs are selected, the timeline shows each API in a separate line with a legend separating each line. You can also zoom in on a selected time range by selecting that area in the chart. To restore to the original view use the Zoom out button on the top right-hand corner of the plot.

    -

    API usage over time

    -
    • -
  • -

    API Usage By Application

    -

    This widget shows the per-application breakdown of requests for the APIs you selected. You can use the pie chart view or the line chart view. You can switch between the two views using the small icon at the upper-right corner of the widget.

    -

    API usage by application

    -
    • -
  • -

    API Usage By Target

    -

    This widget shows the per-backend breakdown of requests for the APIs you selected. This information is useful when multiple APIs share the same backend that has traffic restrictions. You can use these stats to scale your backends proactively. You can switch between the two views using the small icon at the upper-right corner of the widget.

    -

    API usage by target

    -
    • -
  • -

    API Resource Usage

    -

    This table shows a resource-level breakdown of API traffic. Each row represents an API resource and it shows the API name, resource path, API method, and the hit count for that combination.

    -

    API resource usage

    -
    • -
-

Errors

-

The Errors page shows information related to erroneous API calls that are received by your system. The errors are categorized based on the error type. You can further drill down using the error subtypes. Use this page as the starting point for debugging any API errors.

-

Error statistics

-

You can filter the information displayed in the widgets as follows:

- - - - - - - - - - - - - - - - - - - - - -
Filtering OptionDescription
By APIIn the API field, select the APIs for which you want to view analytics. By default, all APIs are selected. You can select one or multiple APIs from this selector and view the aggregated result.
By CategoryThe Category field is displayed when you click Category in the upper right corner of the page. In this field, you can select one or all of the following error categories:
Authentication: Any kind of authentication error falls into this category including expired/missing/invalid credentials.
Target Connectivity: Any kind of back-end error falls into this category including connection time-outs/other back-end errors (for example, 4xx and 5xx status codes).
Throttling: Any request that fails due to rate-limiting falls into this category including application throttling/subscription throttling.
Other: All other errors fall into this category including mediation errors/resource not found errors.
By Status CodeThe Status Code field is displayed when you click Status Code in the upper right corner of the page. In this field, you can select all or any available HTTP status code categories (4xx, 5xx, etc.). These status codes represent the response status of the API Gateway.
-

Viewing errors by category

-

The following widgets are available for monitoring errors when you have selected Category in the upper-right corner of the page.

-
    -
  • -

    This graph shows the error by category over time for the selected period. Apply the required filters as explained above to select the APIs and the error categories to which this content applies. When you select multiple APIs, the error count is grouped by category.

    -

    Errors by category graph

    -
    • -
  • -

    This table provides further information about the errors such as application details and the error reason. For some authentication errors, the application name is not available. You can use this table to get more concrete information about the errors related to your APIs and then start the problem identification.

    -

    Errors by category table

    -
    • -
-

Viewing errors by status code

-

The following widgets are available for monitoring errors when you select Status Code in the upper-right corner of the page.

-
    -
  • -

    Errors by Status Code

    -

    This graph shows the distribution of HTTP status codes received for errors over time for the selected period. Apply the required filters as explained above to select the APIs and status code groups to which this content applies. When you select multiple APIs, the error count is grouped by the status code.

    -

    Errors by status code

    -
    • -
  • -

    Target Errors by Status Code

    -

    This graph shows the distribution of target errors that have occurred during the selected time interval by HTTP status code. Apply the required filters as explained in the table above to view the APIs and status code groups to which this content applies. If you select multiple APIs, the widget groups the target error count by the status code.

    -

    Target errors by status code

    -
    • -
  • -

    Errors

    -

    The Errors heat map shows the HTTP response codes of errors sent to the client by the API Gateway. Each row displays the number of times the system returned each status code for the selected APIs. The cell color is red for higher numbers and white for lower numbers. If required, you can further filter the results by the error code groups you identified with the Errors by Status Code graph.

    -

    Errors

    -
    • -
  • -

    Target Errors

    -

    The Target errors heat map shows the HTTP response codes of errors that the API Gateway received from the backend. Each row displays the number of times the system returned each status code for the selected APIs. The cell color is red for higher numbers and white for lower numbers. If required, you can further filter the results by the error code groups you identified with the Target Errors by Status Code graph.

    -

    Target errors

    -
    • -
-

Latency

-

The Latency page shows information related to the latency of API calls within the API management deployment. You can view a summary of the slowest APIs and then drill down into the API view for further analysis. Use this page as a starting point to debug API slowness.

-

Latency

-

The information displayed is as follows:

-
    -
  • -

    Top 10 Slowest APIs

    -

    This widget allows you to identify the slowest APIs of the API management system at a glance. Since these are the APIs that contribute to the higher 95th percentile of the system, improving these APIs lowers the 95th percentile of latency in the API Management deployments.

    -

    Slowest APIs

    -
    • -
  • -

    Latencies By Category

    -

    This widget allows you to further drill down details in the above chart. Use the API selector in this widget to select the slow API you identified in the earlier step and then analyze further. Use the charts available in the widget to view the 95th percentile and the median latency over the selected period of the following:

    -
      -
    • Backend
      • -
    • Request mediation
      • -
    • Response mediation
      • -
    -

    Latencies by category

    -
    • -
-

You can use these charts to further drill down and analyze whether the latency occurs in the backend, request mediation, or response mediation. Also, because you can see both the median and 95th percentile, you can easily identify whether the slowness is occurring in each request or whether it is intermittent.

-

Cache

-

The Cache page shows statistics that indicate the efficiency with which response caching is carried out for the requests sent to your APIs.

-

Cache statistics

-

The page displays the following statistics:

-
    -
  • -

    Cache Hit Percentage

    -

    This graph shows the percentage of requests the system has handled via the response cache over time and the total hits over time. This information allows you to assess how efficiently the backend handles API requests. For example, if the cache hit rate is low, it may indicate that the backend generates the same response each time a specific request is sent instead of returning the response via the cache. In such a scenario, there is scope to improve performance via response caching.

    -

    Cache hit percentage

    -
    • -
  • -

    Latency

    -

    This section shows the total latency reported during the same time interval applied to the Cache Hit Percentage graph above.

    -

    Cache hits and misses

    -
    • -
-

Devices

-

The Devices page displays information about operating systems and HTTP agents that end users use to invoke the APIs. You can use this page to get an idea of the distribution of your user base and improve your APIs to match the audience.

-

Device statistics

-

To filter the information displayed on this page by API, select the required API(s) in the API field. All is selected by default.

-

The information displayed is as follows:

-
    -
  • -

    Top Platforms

    -

    This chart shows the breakdown of the API clients by the operating system. The pie chart only shows platforms with a significant amount of requests. Other platforms are grouped under the Other category.

    -

    Top platforms

    -
    • -
  • -

    Top User Agents

    -

    This chart shows the breakdown of the API clients by user-agent. The pie chart only shows user agents with a significant amount of requests. Other platforms are grouped under the Other category.

    -

    Top user agents

    -
    • -
-

Alerts

-

The Alerts page shows information related to business alerts issued by Choreo for your currently selected environment and organization. You can use this page as a health monitoring dashboard and make it visible to your project team. Using this page you can drill down on each alert and discover possible anomalies in your published APIs. See the topics given below to get details of the available widgets and understand how to use them effectively.

-

Alerts statistics

-

Prerequisites

-

To use this page, be sure to configure alerts and have API invocations that trigger alerts.

-
-

Note

-

Alerts are retained only for a week.

-
-
    -
  • -

    Alert Summary

    -

    This table lists each alert generated during the selected time interval. The message of the alert can be viewed by expanding the arrow icon on the details column. The drop-downs can be used to filter alerts based on the alert type and API.

    -

    Alert summary

    -
    • -
  • -

    Top APIs by Alert Count

    -

    This shows a pie chart and a table to visualize the alert distribution during the selected time interval.

    -

    Top APIs by alert count

    -
    • -
-

Reports

-

The Reports page allows you to download monthly usage reports for your system. There are preconfigured reports with system-wide statistics, and a custom report generator to generate reports based on a subset of APIs/applications.

-

Report page

-

Download custom reports

-

This widget allows you to generate a custom report for the statistics that have been generated up to now and download it.

-

Custom report download

-

To generate a custom report, follow the steps below:

-
    -
  1. -

    In the API field, select one or more APIs for which you want to generate the report. If required, you can select all the APIs by selecting All.

    -
    2. -
  2. -

    If you need to further filter the content printed in the report, select one or more applications in the Application field. By default, all the applications that have subscribed to one or more of the selected APIs are selected.

    -
    -

    Tip

    -

    If you want to filter the report content by the API consumer instead of the application, click on the toggle switch to the right of the Application field, and then select the required consumer. Only consumers who have subscribed to one or more of the selected APIs are displayed in the list. You can either select one or all of them.

    -
    -
    3. -
  3. -

    Select the required year and the month in the Year and Month fields to specify the time interval for which you want to generate the report.

    -
    4. -
  4. -

    Click Download, and select the required format.

    -
    5. -
-

The report is downloaded in the specified format. The following is a sample report generated in PDF format.

-

Sample report

-

The contents of the report are as follows.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
ItemDescription
Generated TimeThe date and the time the report was generated.
OrganizationThe organization to which the report applies. Each report always applies to a specific organization.
EnvironmentThe environment to which the report applies. Each report always applies to a specific environment.
TenantThe tenant to which the report applies. Each report always applies to a specific tenant.
Reporting periodThe time interval for which the report is generated.
Total request countThe total request count received by all selected APIs during the report time interval.
-

The table in the report contains the following rows.

- - - - - - - - - - - - - - - - - - - - - -
ItemDescription
APIThe name of the API.
ApplicationThe name of the application. The name of the subscriber is also provided within brackets.
UsageThe usage count.
-

Download pregenerated reports

-

These widgets allow you to download monthly reports for the last three months.

-

Pre-generated reports

-

To download a pregenerated report, click Download for the relevant month and then click on the required format.

-

Geo Map

-

The Geo Map page allows you to see a geographical representation of your API usage. You can use this page to make business decisions such as identifying growing regions, analyzing the impact of a region-specific marketing campaign, etc.

-

Geo Map page

-

To filter the information displayed on this page by API, select the required API(s) in the API field. The default value is All.

-

This heat map highlights the countries with the appropriate color based on the hit count. It uses a relative color scale to depict the highest hit count to the lowest non-zero hit count.

-

Geo Map Hit Scale

-

Viewing the number of requests by country

-

You can hold the pointer over the highlighted countries to view the country name and the total number of hits from that location. You can also use the mouse to zoom the map or pan it. Optionally, you can download geo-map data in a tabular format using the PDF or CSV download options by clicking download on the top right corner.

-

Geo Map by country

-
-

Note

-
    -
  • Currently, this feature is only available for on-premises environments.
    • -
  • The geo-map page utilizes the IP address of the incoming request to derive the geolocation. The actual source IP address can be replaced if there are intermediate hosts between the client and the gateway node. Therefore, the reverse proxy or the load balancer fronting the gateway node must add the x-forwarded-for header to each request to preserve the source IP address. If you do not configure this correctly, the Geo Map page will not show any data. To test this, you can manually add an x-forwarded-for header to the request.
    • -
-
- - - - - - -
-
- - -
- - - -
- - -
- - - -
-
-
- - - - - - - - - - - - - - - - - \ No newline at end of file diff --git a/en/site/monitoring-and-insights/integrate-choreo-with-moesif/index.html b/en/site/monitoring-and-insights/integrate-choreo-with-moesif/index.html deleted file mode 100644 index 682930d6c..000000000 --- a/en/site/monitoring-and-insights/integrate-choreo-with-moesif/index.html +++ /dev/null @@ -1,3300 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - Integrate Choreo with Moesif - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- - - -
- - - - - - -
- - -
- -
- - - - - - - -
-
- - - -
-
-
- - - - -
-
-
- - - -
-
-
- - - -
-
-
- - - -
-
- - - - - - - - - - - - - - - - - - - - -

Integrate Choreo with Moesif

-

Moesif is an API analytics and monetization service that helps you grow your API products. You can integrate Choreo with Moesif and gain valuable insights into your API's usage. While Moesif's API analytics capabilities empower you to make informed decision-making on behalf of your organization, its monetization options simplify revenue generation from your APIs, eliminating the need for complex coding.

-

In this guide, you will:

-
    -
  • Generate a key in Moesif.
    • -
  • Configure Choreo to connect to Moesif.
    • -
  • Invoke an API and observe the insights on the Moesif dashboard.
    • -
-

Step 1: Generate an API key in Moesif

-

Let's generate an API key in Moesif. -If you're an existing Moesif user with a registered organization, proceed to step 1.2.

-

Step 1.1: Generate a key in Moesif as a new user

-

If you are a new user, follow the steps below to register an organization and generate a key:

-
    -
  1. Go to https://www.moesif.com/.
    2. -
  2. Click Sign Up and select an authentication option and proceed.
    3. -
  3. -

    On the Get Started page, enter meaningful values for the fields and create a new organization.

    - - - - - - - - - - - - - - - - - -
    FieldDescription
    Organization NameThe name of your company or team.
    Application NameThe name of your application that represents one project or environment.
    -
    4. -
  4. -

    Click Next.

    -
    5. -
  5. -

    On the Overview page, click Next.

    -

    This opens the Quick Install page. As there is no data, you cannot proceed. Let's configure Moesif to receive data from Choreo.

    -
    6. -
  6. -

    Select a WSO2 Choreo as the Server Integration

    -
    7. -
  7. -

    Copy the Application Id.

    -

    First Time user API Key

    -
    8. -
-

Step 1.2: Access the API key in Moesif as an existing user

-

If you are an existing user with a registered organization, or you do not have an API key for the organization you created, follow the steps below to access the generated API key:

-
    -
  1. Go to https://www.moesif.com/.
    2. -
  2. Click on your profile in the bottom left corner, and navigate to the API Keys page.
    3. -
  3. Copy the Collection Application Id.
    4. -
-

Step 2: Integrate Choreo with Moesif

-

Let's configure Choreo to publish events to Moesif.

-
    -
  1. Go to https://console.choreo.dev/ and sign in.
    2. -
  2. On the left navigation, click Settings.
    3. -
  3. In the header, click the Organization list. This will open the organization level settings page.
    4. -
  4. Click the API Management tab, and click Moesif Dashboard.
    5. -
  5. Select the environment you want to publish data for.
    6. -
  6. Paste the Application Id you copied.
    7. -
  7. Click Add.
    8. -
-

Once you successfully add the key, you will see a delete option next to it. Currently, you can only configure one API key. If you need to add a new API key, you need to delete the existing key and add the new one.

-
-

Note

-

Once you configure the Moesif API key on Choreo, wait for five minutes before you publish any data to the Moesif API analytics platform.

-
-

Step 3: Invoke an API and observe the data on the Moesif Dashboard

-

You have configured Choreo to publish data to Moesif. Let's see how you can view the insights on Moesif.

-
-

Tip

- -
-
    -
  1. -

    Invoke your API by following the Test REST Endpoints via the OpenAPI Console guide.

    -
    2. -
  2. -

    Once you publish data, your Moesif dashboard will receive events. Once Moesif receives events, you will see a notification on Moesif confirming that it received data.

    -

    Data Recieved Moesif Notification

    -
    3. -
  3. -

    Click Next on the notification. This will take you to the final step, where you can opt to add team members. In this guide, let's skip this step.

    -
    4. -
  4. Click Finish.
    5. -
-

You can now view your API's insights in the Moesif dashboard.

- - - - - - -
-
- - -
- - - -
- - -
- - - -
-
-
- - - - - - - - - - - - - - - - - \ No newline at end of file diff --git a/en/site/monitoring-and-insights/logs/view-pdp-logs/index.html b/en/site/monitoring-and-insights/logs/view-pdp-logs/index.html deleted file mode 100644 index d87656393..000000000 --- a/en/site/monitoring-and-insights/logs/view-pdp-logs/index.html +++ /dev/null @@ -1,3133 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - View Private Data Plane (PDP) Logs - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- - - -
- - - - - - -
- - -
- -
- - - - - - - -
-
- - - -
-
-
- - - - -
-
-
- - - -
-
-
- - - -
-
-
- - - -
-
- - - - - - - - - - - - - - - - - - - - -

View Private Data Plane (PDP) Logs

-

Choreo offers the capability to access runtime logs through its console. However, in cases where viewing logs for your PDP is not supported by Choreo yet, you can still view the runtime logs of your components via the log analyzing solution provided by your cloud vendor as a workaround.

-

Prerequisites

-

Before you try out this guide, complete the following:

-
    -
  1. Go to https://console.choreo.dev/, and sign in using your preferred method.
    2. -
  2. Select your component from Components Listing. This will open the Overview page of your component.
    3. -
  3. In the left navigation menu, click Runtime under DevOps.
    4. -
  4. Copy the Release ID and the Namespace. Save it for later.
    5. -
-

View Private Data Plane (PDP) logs with Azure Log Analytics

-

You can view your PDP logs with Azure Log Analytics by following the steps below:

-
    -
  1. Go to https://portal.azure.com/.
    2. -
  2. Follow the Azure Log Analytics Tutorial and open log analytics of your relative log analytics workspace.
    3. -
  3. Copy and paste the query below into the query editor.
    4. -
  4. Replace the <START_TIME_STAMP EX: 2023-04-10T07:07:31.684Z> and <END_TIME_STAMP EX: 2023-04-21T07:27:31.684Z> values as required. Replace the '' and '' with the values you copied by following the steps in the prerequisites section. Replace the <OPTIONAL SEARCH PHRASE> with your search term, or leave it blank if you don't require any search filtering.
    5. -
  5. Run the query to extract the relevant logs.
    6. -
-
let startDateTime = datetime('<START_TIME_STAMP EX: 2023-04-10T07:07:31.684Z>');
-let endDateTime = datetime('<END_TIME_STAMP EX: 2023-04-21T07:27:31.684Z>');
-let releaseId = '<RELEASE_ID>';
-let namespace = '<NAMESPACE>';
-let searchPhrase = '<OPTIONAL SEARCH PHRASE>';
-let startDateTimeKPI = iff(datetime_diff('second', endDateTime, startDateTime) > 60, startDateTime, endDateTime - 2m);let endDateTimeKPI = iff(datetime_diff('second', endDateTime, startDateTime) > 60, endDateTime, startDateTime + 2m);let filteredLogLevels = dynamic([]);
-let hasNoLevelFilter = array_length(filteredLogLevels) == 0;
-let commonKeys = dynamic(['time', 'level', 'module', 'traceId', 'spanId', 'message']);
-let ContainerIdList = KubePodInventory
-| where TimeGenerated > startDateTimeKPI and TimeGenerated < endDateTimeKPI
-| where Namespace == namespace
-| where extractjson('$.[0].release_id', PodLabel) == releaseId
-| distinct ContainerID;
-let data = ContainerLog
-| where TimeGenerated > startDateTime and TimeGenerated < endDateTime
-| where ContainerID in (ContainerIdList)
-| where searchPhrase == "" or LogEntry contains searchPhrase
-| top 126 by TimeGenerated desc
-| extend logs = parse_json(LogEntry)
-| project TimeGenerated, 
-LogLevel = iif(isempty(logs['level']), iff(LogEntrySource == 'stderr', 'ERROR', 'INFO'), logs['level']), 
-LogEntry = iif(isempty(logs['message']), logs, logs['message']),
-KeyValuePair = bag_remove_keys(logs, commonKeys)
-| where hasNoLevelFilter or LogLevel in (filteredLogLevels);
-let lastTimeStamp = data 
-| top 1 by TimeGenerated asc | project TimeGenerated;
-let trimmedData = data | where TimeGenerated > toscalar(lastTimeStamp)| sort by TimeGenerated desc;
-let selected = iff(toscalar(data | count) == 126, 'trimmedData', 'data');
-let choose = (selector:string){   union   (trimmedData | where selector == 'trimmedData'),    (data | where selector == 'data')};
-choose(selected);
-
- -

View Private Data Plane (PDP) logs with Amazon CloudWatch

-
    -
  1. Go to https://portal.azure.com/.
    2. -
  2. Follow the AWS Analyzing Log Data documentation and open Log Insights.
    3. -
  3. Select the relevant region and the relevant log group (the log group string has the cluster name and “/application” appended at the end).
    4. -
  4. Select the required time range.
    5. -
  5. Copy the query below and paste it into the query editor.
    6. -
  6. Replace the <RELEASE_ID> with the values you copied by following the steps in the prerequisites section. Replace the <OPTIONAL SEARCH PHRASE> with your search term, or leave it blank if you don't require any search filtering.
    7. -
  7. Run the query to extract the logs.
    8. -
-
fields @timestamp, @message
-| filter kubernetes.labels.release_id == "<RELEASE_ID>"
-| filter @message like "<OPTIONAL SEARCH PHRASE>"
-
- - - - - - -
-
- - -
- - - -
- - -
- -
-
-
-
- Copyright © WSO2 LLC (2023-2024) -
-
- Content licensed under CC By 4.0. | Sample code - licensed under Apache 2.0. -
-
-
-
-
- - - -
-
-
- - - - - - - - - - - - - - - - - \ No newline at end of file diff --git a/en/site/monitoring-and-insights/observability-overview/index.html b/en/site/monitoring-and-insights/observability-overview/index.html deleted file mode 100644 index 46eb27b8d..000000000 --- a/en/site/monitoring-and-insights/observability-overview/index.html +++ /dev/null @@ -1,3197 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - Observability Overview - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- - - -
- - - - - - -
- - -
- -
- - - - - - - -
-
- - - -
-
-
- - - - -
-
-
- - - -
-
-
- - - -
-
-
- - - -
-
- - - - - - - - - - - - - - - - - - - - -

Observability Overview

-

The Choreo observability dashboard provides a comprehensive interface to visualize and monitor the performance of services deployed on Choreo.

-

Dashboard overview

-

The Observability dashboard allows you to:

-
    -
  • Observe the throughput and latencies of requests served over a given period.
    • -
  • Compare metrics side-by-side to facilitate efficient diagnosis.
    • -
  • Observe the diagnostics view generated over a given period.
    • -
  • View logs generated over a specific timeframe.
    • -
-
-

Tip

-

If you are a Choreo private data plane customer and you want to observe your private data plane using New Relic, see Observing Choreo Private Data Planes With New Relic.

-
-

Throughput and latency graphs

-

The throughput graph depicts the throughput of requests per second for a selected timestamp.

-

Throughput and latency graph

-

By default, Choreo renders this graph for the data generated within the past 24 hours. You can change the default time window by selecting the time range and zone from the options bar. To expand the graph, click and drag the cursor over the period you want to drill down.

-

You can view the Choreo service logs in the Logs pane below the throughput and latency graph. Clicking on a graph updates the Logs view to contain the corresponding log entries generated at that time. You can use these logs to identify the reasons for any latency and throughput anomalies you detect using the graph.

-

Diagnostics view

-

The Diagnostics view allows you to simultaneously analyze errors, throughput, latencies, CPU usage, memory usage, and logs for a particular event. This facilitates detailed error detection and analysis.

-

By default, the time range selected for the Throughput & Latency graphs is the same time range used for the Diagnostics view.

-

Each horizontal section of the graph, termed a bin, represents a specific period and comprises:

-
    -
  • Date/Time: Indicates when the log entries began to appear.
    • -
  • Logs: List of log entries and respective log counts within the bin's timeframe, sorted by precedence (error logs followed by info logs). Each bin displays a maximum of five log entries.
    • -
  • Error: The number of HTTP errors that occurred at the selected time.
    • -
  • TP: Throughput of the requests at the selected time (req/s).
    • -
  • Latency: Request latency at the selected time (ms).
    • -
  • CPU: CPU usage at the selected time (millicores).
    • -
  • Memory: Memory usage at the selected time (MiB).
    • -
-

Logs

-

The Logs pane serves as a centralized view to observe logs of the components you deploy on Choreo. This facilitates rigorous troubleshooting and analysis.

- - - - - - -
-
- - -
- - - -
- - -
- - - -
-
-
- - - - - - - - - - - - - - - - - \ No newline at end of file diff --git a/en/site/monitoring-and-insights/usage-insights/index.html b/en/site/monitoring-and-insights/usage-insights/index.html deleted file mode 100644 index 7945985b0..000000000 --- a/en/site/monitoring-and-insights/usage-insights/index.html +++ /dev/null @@ -1,15 +0,0 @@ - - - - - - Redirecting... - - - - - - -Redirecting... - - diff --git a/en/site/monitoring-and-insights/view-api-insights/index.html b/en/site/monitoring-and-insights/view-api-insights/index.html deleted file mode 100644 index 5edf3ed6e..000000000 --- a/en/site/monitoring-and-insights/view-api-insights/index.html +++ /dev/null @@ -1,15 +0,0 @@ - - - - - - Redirecting... - - - - - - -Redirecting... - - diff --git a/en/site/monitoring-and-insights/view-logs/index.html b/en/site/monitoring-and-insights/view-logs/index.html deleted file mode 100644 index 7eb2e7872..000000000 --- a/en/site/monitoring-and-insights/view-logs/index.html +++ /dev/null @@ -1,3367 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - View Logs - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- - - -
- - - - - - -
- - -
- -
- - - - - - - -
-
- - - -
-
-
- - - - -
-
-
- - - -
-
-
- - - -
-
-
- - - -
-
- - - - - - - - - - - - - - - - - - - - -

View Logs

-

The unified log view in Choreo allows you to view runtime and audit logs to gain application and user insights while ensuring data privacy.

-

Choreo provides real-time insights through live logs and allows you to view historical logs for insights into the past. You also have the flexibility to define a required time range to view relevant log entries, where an intuitive scrolling capability facilitates easy viewing of appropriate logs within the selected time frame.

-

The log view also provides advanced filtering capabilities that allow you to efficiently navigate through appropriate logs to expedite troubleshooting in distributed environments.

-
-

Note

All personally identifiable information (PII) gets resolved at the frontend service level, with only relevant UUIDs stored in logs.

-

-
-

Runtime logs

-

Choreo runtime logs provide insights into both project and component-level logs, covering application and gateway logs. These logs streamline the debugging process by centralizing diverse log sources.

-

In Choreo, any organization member can view runtime logs via the runtime logs page. Choreo allows you to apply filters based on parameters such as log level (error, warn, info, debug), log type (application, gateway), and environment (development, staging, production) to simplify the debugging process.

-

To access runtime logs, follow the steps below:

-
    -
  1. Sign in to Choreo.
    2. -
  2. -

    In the left navigation menu, click Observability and then click Runtime Logs. This displays runtime logs for the past 30 days by default.

    -

    To view logs based on a specific time range and other requirements, you can apply the necessary filter criteria.

    -

    Runtime logs

    -
    3. -
-

Understand runtime logs

-

When you view component-level logs on the Runtime Logs page, you will see both application and gateway logs.

-

Application logs

-

Each application log entry displays the following details:

-
    -
  • timestamp: The time when the request is received by the component.
    • -
  • level: Indicates the severity of the log message. Possible values are Debug, Info, Warn, and Error.
    • -
  • componentVersion: The version of the invoked component.
    • -
  • componentVersionId: The identifier of the invoked component’s version.
    • -
  • envName: The environment of the inbound request. For example, Development, Production, etc.
    • -
-

Gateway logs

-

Each gateway log entry displays the following details:

-
    -
  • timestamp: The time when the request is received by the gateway component.
    • -
  • logLine: Contains the following details about the request, including inbound and outbound information from the gateway perspective.
      -
    • Method: The HTTP method of the request.
      • -
    • RequestPath: The path of the inbound request.
      • -
    • ServicePath: The path of the outbound request.
      • -
    • UserAgent: The user-agent header of the request.
      • -
    • CorrelationID: The request identifier of the inbound request. This is useful to track a request.
      • -
    • ServiceHost: The host IP of the backend.
      • -
    • Duration: The time taken for the gateway to serve the request.  
      • -
    -
    • -
  • -

    gatewayCode: Indicates the state of the request from the gateway perspective. Possible values are as follows:

    -
      -
    • BACKEND_RESPONSE: Indicates successful processing of the request by the gateway with a response to the client from the backend application.
      • -
    • CORS_RESPONSE: Denotes a CORS (Cross Origin Resource Sharing) request.
      • -
    • AUTH_FAILURE: Indicates a request failure at the gateway due to authentication or authorization issues, such as an invalid token.
      • -
    • NO_HEALTHY_BACKEND: Indicates a request failure at the gateway due to a non-existent backend.
      • -
    • RATE_LIMITED: Indicates a request failure at the gateway due to surpassing the rate limit enforced within the component.
      • -
    • RESOURCE_NOT_FOUND: Indicates a request failure at the gateway due to the absence of a matching API resource for the inbound request. This can be caused by a mismatch in the HTTP method, path, or host.
      • -
    • BACKEND_TIMEOUT: Indicates a request timeout when calling the backend application from the gateway.
      • -
    • GATEWAY_ERROR: Indicates a request failure due to an erroneous behavior in the gateway.
      • -
    -
    -

    Note

    -

    Occasionally, a request may not fit into any of the above categories. In such instances, the gatewayCode is displayed as UNKNOWN.

    -
    -
    • -
  • -

    statusCode: The HTTP status code returned to the client.

    -
    • -
  • componentVersion: The version of the invoked component.
    • -
  • envName: The environment of the inbound request. For example, Development, Production, etc.
    • -
-

Audit logs

-

Audit logs, also called audit trails, enhance security, ensure compliance, provide operational insights, and help manage risks.

-

In Choreo, an audit log records organization-level user-specific operations performed via the Choreo Console. It also captures the timestamp and the outcome of the action.

-

As of now, Choreo captures the following user-specific operations as audit logs:

-
    -
  • Project creation, update, and deletion.
    • -
  • Component creation, update, and deletion.
    • -
  • Component promotion initiation.
    • -
  • Component version creation.
    • -
  • Component deployment, redeployment, and undeployment initiation for all components other than REST API Proxy components.
    • -
  • Component API access mode update.
    • -
  • Enabling and disabling component auto-deployment on commit.
    • -
  • Component build configuration update.
    • -
  • Component endpoint creation, update, and deletion.
    • -
  • Organization user management.
    • -
  • On-premises key management.
    • -
  • Project-level configuration management.
    • -
-

In Choreo, organization administrators are allowed to view audit logs by default. If other members need to access organization-specific audit logs, the administrator can create a role with the relevant permission and assign it to members. For step-by-step instructions on how to create and assign a role with relevant permission, see Manage audit log access.

-

To view audit logs, follow these steps:

-
    -
  1. Sign in to Choreo.
    2. -
  2. -

    In the Choreo Console, go to the top navigation menu and click Organization.

    -
    -

    Tip

    -

    As of now, you can only view organization-level audit logs.

    -
    -
    3. -
  3. -

    In the left navigation menu, click DevOps and then click Audit Logs. This displays audit logs for the past 30 days by default.

    -

    To view audit logs based on a specific time range and other requirements, you can apply the necessary filter criteria.

    -

    Audit logs

    -
    4. -
-

Audit log retention

-

Choreo retains audit logs for one year and archives them for an additional year. Therefore, the total retention period for audit logs is two years.

-

Manage audit log access

-

Follow the steps given below to create a role with audit log access permission and assign it to organization members who need access to audit logs:

-
-

Note

You must be the organization administrator to perform this action.

-

-
-

Step 1: Create a role with audit log access permission

-
    -
  1. In the Choreo Console, go to the top navigation menu and click Organization.
    2. -
  2. In the left navigation menu, click Settings.
    3. -
  3. On the Organization tab, click Roles and then click + Create Role.
    4. -
  4. -

    Enter a name and description for the role.

    -

    Create role

    -
    5. -
  5. -

    Click Next.

    -
    6. -
  6. -

    In the Create Role dialog, select LOG-MANAGEMENT under Permissions.

    -

    Select log management permission

    -
    7. -
  7. -

    Click Create.

    -
    8. -
-

Step 2: Assign the created role to an organization member

-
    -
  1. On the Organization tab, click Members. This lists the members of the organization with their respective details.
    2. -
  2. -

    Click on a member who needs to have access to audit logs, and then click + Add Role.

    -
    -

    Tip

    -

    If you want to invite one or more members and assign them the audit log viewer role, follow the steps given below:

    -
      -
    1. Click + Invite Member and then click to expand the Roles list.
      2. -
    2. Select the role you created in Step 1.
      3. -
    3. In the Emails field, enter the email addresses of members you want to invite and grant permission to access audit logs.
      4. -
    4. Click Invite. This sends an invitation email to each email address so that the members can accept and obtain access to view audit logs.
      5. -
    -
    -
    3. -
  3. -

    Click to expand the Roles list and select the role you created in Step 1.

    -
    4. -
  4. Click Add. This assigns the selected role to the member.
    5. -
- - - - - - -
-
- - -
- - - -
- - -
- - - -
-
-
- - - - - - - - - - - - - - - - - \ No newline at end of file diff --git a/en/site/monitoring-and-insights/work-with-choreo-insights-api/access-the-choreo-insights-api/index.html b/en/site/monitoring-and-insights/work-with-choreo-insights-api/access-the-choreo-insights-api/index.html deleted file mode 100644 index e33ea6b55..000000000 --- a/en/site/monitoring-and-insights/work-with-choreo-insights-api/access-the-choreo-insights-api/index.html +++ /dev/null @@ -1,3234 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - Access the Choreo Insights API - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- - - -
- - - - - - -
- - -
- -
- - - - - - - -
-
- - - -
-
-
- - - - -
-
-
- - - -
-
-
- - - -
-
-
- - - -
-
- - - - - - - - - - - - - - - - - - - - -

Access the Choreo Insights API

-

The Usage Insights page in the Choreo Console displays data retrieved from the Insights API exposed over the Internet. However, in some scenarios, you may need to retrieve data from external systems and implement custom dashboards to display the data.

-

Choreo provides a secure and user-friendly approach to accomplish this requirement. Follow the steps given below:

-

Become a member of the Choreo System organization

-
    -
  1. -

    Access the Developer Portal of the Choreo System organization via https://devportal.choreo.dev/choreosystem/applications and sign in using your preferred method.

    -
    2. -
  2. -

    To obtain access to the Choreo System organization, click Request Access.

    -

    Request access

    -
    3. -
-

Create an application and generate keys

-

To create an application and generate keys, follow the steps below:

-
    -
  1. -

    To create a new application in the Choreo System organization, click + Create Application.

    -
    2. -
  2. -

    Enter a name for the application and click Create. This creates the application and takes you to the Overview page.

    -
    3. -
  3. -

    To subscribe to the Insights API via the newly created application, follow the steps below:

    -
      -
    1. In the left navigation menu, click Subscriptions.
      2. -
    2. In the Subscription Management pane, click + Add APIs.
      3. -
    3. Search for Insights and click Add.
      4. -
    -
    4. -
  4. -

    To generate credentials for the application, follow the steps given below:

    -
      -
    1. In the left navigation menu, click Production under Credentials.
      2. -
    2. Click Generate Credentials. Choreo generates tokens and populates the Consumer Key and Consumer Secret fields in the Application Keys pane.
      3. -
    -
    5. -
  5. -

    To specify an appropriate token expiry time for the application, follow the steps given below:

    -
      -
    1. In the Application Keys pane, click to expand Advanced Configurations.
      2. -
    2. -

      Specify an appropriate value in the Application access token expiry time field and click Update.

      -

      Update token expiry time

      -
      3. -
    -
    6. -
  6. -

    Execute the following cURL command to generate an access token:

    -
    curl --location --request POST 'https://sts.choreo.dev/oauth2/token' \
---header 'Authorization: Basic <BASE64_ENCODED_CONSUMER_KEY_AND_CONSUMER_SECRET_OF_YOUR_APP_HERE>' \
---header 'Content-Type: application/x-www-form-urlencoded' \
---data-urlencode 'grant_type=client_credentials' \
---data-urlencode 'orgHandle=<YOUR_ORG_HANDLE_HERE>' \
---data-urlencode 'scope=apim:api_manage'
-
    - -
    -

    Info

    -

    To obtain your organization handle, follow the steps given below:

    -
      -
    1. Go to https://console.choreo.dev and sign in using your preferred method.
      2. -
    2. In the Choreo Console, click your username in the top right corner.
      3. -
    3. In the drop-down menu, click Settings.
      4. -
    4. In the Organization pane, click Copy Handle.
      5. -
    -
    -

    You can use the generated token to access the Insights API exposed via https://choreocontrolplane.choreo.dev/93tu/insights/1.0.0/query-api.

    -

    The following is a sample cURL command to invoke the Insights API:

    -
    curl --location --request POST 'https://choreocontrolplane.choreo.dev/93tu/insights/1.0.0/query-api' \
---header 'Content-Type: application/json' \
---header 'Authorization: Bearer <TOKEN_HERE>' \
---data-raw '{"query":"query ($org: OrgFilter!) {listEnvironments(org: $org){id\n name}}","variables":{"org":{"orgId":"<ORG_UUID_HERE>"}}}'
-
    - -
    -

    Tip

    -
      -
    • When the token expires, you can generate a new token programmatically by making an API call to the token endpoint using the client credentials grant type.
      • -
    • If a token theft occurs, you can revoke the token by making an API call to the revoke endpoint.
      • -
    -

    Endpoints

    -
    -
    7. -
- - - - - - -
-
- - -
- - - -
- - -
- - - -
-
-
- - - - - - - - - - - - - - - - - \ No newline at end of file diff --git a/en/site/monitoring-and-insights/work-with-choreo-insights-api/choreo-insights-api/index.html b/en/site/monitoring-and-insights/work-with-choreo-insights-api/choreo-insights-api/index.html deleted file mode 100644 index 57a2a00df..000000000 --- a/en/site/monitoring-and-insights/work-with-choreo-insights-api/choreo-insights-api/index.html +++ /dev/null @@ -1,9103 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - Choreo Insights API - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- - - -
- - - - - - -
- - -
- -
- - - - - - - -
-
- - - -
-
-
- - - - -
-
-
- - - -
-
-
- - - -
-
-
- - - -
-
- - - - - - - - - - - - - - - - - - - - -

Choreo Insights API

-

The Choreo Insights API is a GraphQL API that allows you to retrieve data from external systems based on specific criteria. This guide describes the operations and schema-defined types you can use to retrieve data via the Choreo Insights API.

- -

Try out

-

You can try out the Choreo Insights API with your data via GraphQL Explorer.

-
-

Warning

-

The GraphQL Explorer is currently not compatible with the Safari web browser due to a known issue.

-
-

Query

-

The query root of the Choreo Insights GraphQL API.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldArgumentTypeDescription
listAllAPI[API] - -Fetches all the APIs with the given combination of tenant ID, environment ID, and organization ID. Optionally, you -can configure the provider parameter to further filter the APIs by a specific provider. - -
providerString - -The name of the API provider. - -
dataFilterDataFilter! - -The data filter. - -
listApplications[Application] - -Fetches all the applications with the given combination of tenant ID, environment ID, and organization ID. Optionally, you -can configure the applicationFilter parameter to further filter the applications by a specific application filter. - -
applicationFilterApplicationFilter - -The application filter. - -
dataFilterDataFilter! - -The data filter. - -
listProviders[Provider] - -Fetches all the API providers with the given combination of tenant ID, environment ID, and organization ID. - -
dataFilterDataFilter! - -The data filter. - -
listSubscribers[Subscriber] - -Fetches all the API subscribers with the given combination of tenant ID, environment ID, and organization ID. Optionally, you -can configure the subscriberFilter parameter to further filter the subscribers. - -
subscriberFilterSubscriberFilter - -The subscriber filter. - -
dataFilterDataFilter! - -The data filter. - -
listOrganizations[Organization] - -Fetches all the organizations of a user. - -
listEnvironments[Environment] - -Fetches all the environments of an organization. - -
orgOrgFilter! - -The organization filter. - -
projectIdString - -The project ID by which the results need to be filtered. It is optional to specify a value for this -parameter. Note that providing a project ID with an on-prem key is not allowed. - -
listTenants[String] - -Fetches all the tenants with the given combination of environment ID and organization ID. - -
tenantDataFilterTenantDataFilter! - -The tenant filter. - -
getTotalTrafficInt - -Returns the total traffic during the given time range for the specified combination of tenant ID, environment ID, -and organization ID. - -
filterTimeFilter! - -The time filter. - -
dataFilterDataFilter! - -The data filter. - -
getTotalErrorsInt - -Returns the total number of errors that occurred during the given time range for the specified combination of tenant -ID, environment ID, and organization ID. - -
filterTimeFilter! - -The time filter. - -
dataFilterDataFilter! - -The data filter. - -
getOverallLatencyFloat - -Returns the overall response latency (95th percentile value) during the given time range for the specified -combination of tenant ID, environment ID, and organization ID. - -
filterTimeFilter! - -The time filter. - -
dataFilterDataFilter! - -The data filter. - -
getLatencySummaryLatencySummary - -Returns the response latency value (95th percentile value) for each time granularity within the specified time range -for the given combination of tenant ID, environment ID, and organization ID. Optionally, you can configure the -latencySummaryFilter parameter to further filter the results. - -
filterTimeFilter! - -The time filter. - -
latencySummaryFilterLatencySummaryFilter - -The latency summary filter. - -
dataFilterDataFilter! - -The data filter. - -
getSuccessSummarySuccessSummary - -Returns the number of successful (2xx response code) hit count for each time granularity within the specified time -range for the given combination of tenant ID, environment ID, and organization ID. Optionally, you can configure the -granularity parameter to override the default granularity value. - -
filterTimeFilter! - -The time filter. - -
dataFilterDataFilter! - -The data filter. - -
granularityString - -The granularity value. - -
getErrorSummaryErrorSummary - -Returns the number of unsuccessful hits (i.e., the total of both 4xx and 5xx response codes) for each time -granularity within the specified time range for the given combination of tenant ID, environment ID, and organization -ID. Optionally, you can configure the granularity parameter to override the default granularity value. - -
filterTimeFilter! - -The time filter. - -
dataFilterDataFilter! - -The data filter. - -
granularityString - -The granularity value. - -
getErrorsByCategoryErrorsByCategory - -Returns the number of proxy errors (i.e., the total of both 4xx and 5xx response codes) by each error category -for each time granularity within the specified time range for the given combination of tenant ID, environment ID, -and organization ID. Optionally, you can configure the errorsByCategoryFilter parameter to further filter the -results. - -
timeFilterTimeFilter! - -The time filter. - -
errorsByCategoryFilterErrorsByCategoryFilter - -The errors by category filter. - -
dataFilterDataFilter! - -The data filter. - -
getErrorsDetailsDetailsOfErrors - -Returns details of each proxy error (for both 4xx and 5xx response codes) within the specified time range for -the given combination of tenant ID, environment ID, and organization ID. Optionally, you can configure the -errorsDetailsFilter parameter to further filter the results. - -
timeFilterTimeFilter! - -The time filter. - -
errorsDetailsFilterErrorsDetailsFilter - -The error details filter. - -
dataFilterDataFilter! - -The data filter. - -
getProxyTargetErrorsOverTime[ErrorsByStatusCodeCategory] - -Returns a list of hit counts for proxy and target errors for each time granularity within the specified time range -for the given combination of tenant ID, environment ID, and organization ID. The errors in each proxy and target -result set are grouped as 4xx, 5xx, and total. Optionally, you can configure the errorsByStatusCodeFilter -parameter to further filter the results. - -
timeFilterTimeFilter! - -The time filter. - -
errorsByStatusCodeFilterErrorsByStatusCodeFilter - -The errors by status code filter. - -
dataFilterDataFilter! - -The data filter. - -
getErrorsByStatusCodeErrorsByStatusCode - -Returns the hit count for each error response code (401, 404, and 500 etc.,) for each API within the specified -time range for the given combination of tenant ID, environment ID, and organization ID. - -
timeFilterTimeFilter! - -The time filter. - -
errorCountByStatusCodeFilterErrorCountByStatusCodeFilter! - -The error count by status code filter. - -
dataFilterDataFilter! - -The data filter. - -
getTotalErrorsByAPITotalError - -Returns the total proxy error hit count for an API across for the given combination of tenant ID, environment ID, -and organization ID. Optionally, you can configure the filter parameter to further filter the results by a given -time range. - -
filterTimeFilter - -The time filter. - -
dataFilterDataFilter! - -The data filter. - -
apiIdID! - -The API ID. - -
getAPIUsageOverTime[APIUsageOverTime] - -Returns a list of details related to the usage of each API over time for each time granularity within the specified -time range for the given combination of tenant ID, environment ID, and organization ID. Optionally, you can -configure the apiUsageOvertimeFilter parameter to further filter the results. - -
timeFilterTimeFilter! - -The time filter. - -
apiUsageOvertimeFilterAPIUsageOverTimeFilter - -The API usage overtime filter. - -
dataFilterDataFilter! - -The data filter. - -
getAPIUsageByAppOverTimeAPIUsageByAppOverTime - -Returns API usage by each application over time for each time granularity within the specified time range for the -given combination of tenant ID, environment ID, and organization ID. Optionally, you can configure the -apiUsageOvertimeFilter parameter to further filter the results. - -
timeFilterTimeFilter! - -The time filter. - -
apiUsageOvertimeFilterAPIUsageOverTimeFilter - -The API usage overtime filter. - -
dataFilterDataFilter! - -The data filter. - -
getAPIUsageByBackendOverTimeAPIUsageByBackendOverTime - -Returns API usage by each backend over time for each time granularity within the specified time range for the given -combination of tenant ID, environment ID, and organization ID. Optionally, you can configure the -apiUsageByBackendOverTimeFilter parameter to further filter the results. - -
timeFilterTimeFilter! - -The time filter. - -
apiUsageByBackendOverTimeFilterAPIUsageByBackendOverTimeFilter - -The API usage by backend overtime filter. - -
dataFilterDataFilter! - -The data filter. - -
getResourceUsageResourceUsages - -Returns API usage by resource within the specified time range for the given combination of tenant ID, environment -ID, and organization ID. Optionally, you can configure the resourceUsageFilter parameter to further filter the -results. - -
timeFilterTimeFilter! - -The time filter. - -
resourceUsageFilterResourceUsageFilter - -The resource usage filter. - -
dataFilterDataFilter! - -The data filter. - -
getTotalTrafficByAPIInt - -Returns the total hit count for an API for the given combination of tenant ID, environment ID, and organization ID. -Optionally, you can configure the filter parameter to further filter the results by a given time range. - -
filterTimeFilter - -The time filter. - -
dataFilterDataFilter! - -The data filter. - -
apiIdID! - -The API ID. - -
topSlowestAPIs[SlowAPI] - -Returns a list of top slowest APIs based on the response latency (95th percentile value) within the specified time -range for the given combination of tenant ID, environment ID, and organization ID. - -
filterTimeFilter! - -The time filter. - -
dataFilterDataFilter! - -The data filter. - -
limitInt! - -The limit for the slow APIs list. - -
getLatencyAPILatency - -Returns different latency category values (95th percentile values) for a given API over time for each time -granularity within the specified time range for the given combination of tenant ID, environment ID, and organization -ID. - -
timeFilterTimeFilter! - -The time filter. - -
latencyFilterLatencyFilter! - -The latency filter. - -
dataFilterDataFilter! - -The data filter. - -
getOverallLatencyByAPIOverallLatency - -Returns the overall response latency (95th percentile value) for an API for the given combination of tenant ID, -environment ID, and organization ID. Optionally, you can configure the filter parameter to further filter the -results by a given time range. - -
filterTimeFilter - -The time filter. - -
dataFilterDataFilter! - -The data filter. - -
apiIdID! - -The API ID. - -
getCacheHitsAndMissesCacheHits - -Return the total number of response cache hits, misses, and hit percentage for an API over time for each time -granularity within the specified time range for the given combination of tenant ID, environment ID, and -organization ID. - -
timeFilterTimeFilter! - -The time filter. - -
cacheFilterCacheFilter - -The cache filter. - -
dataFilterDataFilter! - -The data filter. - -
getTopPlatforms[Platform] - -Returns a list of top platforms ranked based on the hit count within the specified time range for the given -combination of tenant ID, environment ID, and organization ID. The result list includes the top nine platforms with -the respective hit count, and all the rest of the platforms are labeled as **Other** with the cumulated hit count. -Optionally, you can configure the deviceFilter parameter to further filter the results. - -
timeFilterTimeFilter! - -The time filter. - -
deviceFilterDeviceFilter - -The device filter. - -
dataFilterDataFilter! - -The data filter. - -
getTopUserAgents[UserAgent] - -Returns a list of top user agents ranked based on the hit count within the specified time range for the given -combination of tenant ID, environment ID, and organization ID. The result list includes the top nine user agents -with the respective hit count, and all the rest of the platforms are labeled as **Other** with the cumulated hit -count. Optionally, you can configure the deviceFilter parameter to further filter the results. - -
timeFilterTimeFilter! - -The time filter. - -
deviceFilterDeviceFilter - -The device filter. - -
dataFilterDataFilter! - -The data filter. - -
getAPIUsageByGeoLocation[UsageByGeoLocation] - -NOTE: Currently, this operation returns data only for on-premise environments. - -Returns API usage by country within the specified time range for the given combination of tenant ID, environment ID, -and organization ID. Optionally, you can configure the geoLocationFilter parameter to further filter the results. - -
timeFilterTimeFilter! - -The time filter. - -
geoLocationFilterGeoLocationFilter - -The geolocation filter. - -
dataFilterDataFilter! - -The data filter. - -
getAPIsUsageByApplications[APIUsageByApplication] - -Returns details relating to the usage of each API by application within the specified time range for the given -combination of tenant ID, environment ID, and organization ID. Optionally, you can configure the -apiUsageByAppFilter parameter to further filter the results. - -
timeFilterTimeFilter! - -The time filter. - -
apiUsageByAppFilterAPIUsageByAppFilter - -The API usage by app filter. - -
dataFilterDataFilter! - -The data filter. - -
getTopAPIsByAlertCountTopAPIsByAlertCount - -Returns top APIs ranked based on the alert count within the specified time range for the given combination of tenant -ID, environment ID, and organization ID. Optionally, you can configure the topAPIsByAlertCountFilter parameter to -further filter the results. - -
timeFilterTimeFilter! - -The time filter. - -
topAPIsByAlertCountFilterTopAPIsByAlertCountFilter - -The top APIs by alert count filter. - -
dataFilterDataFilter! - -The data filter. - -
getAlertSummaryAlertSummaries - -Returns a summary for each alert within the specified time range for the given combination of tenant ID, -environment ID, and organization ID. Optionally, you can configure the alertSummaryFilter parameter to further -filter the results. - -
timeFilterTimeFilter! - -The time filter. - -
alertSummaryFilterAlertSummaryFilter - -The alert summary filter. - -
dataFilterDataFilter! - -The data filter. - -
getSuccessAPIsUsageByApplications[SuccessAPIUsageByApplication] - -NOTE: This operation can only be invoked via using an on-prem key as the authentication header. - -Returns a list of successful hit counts (i.e., 2xx response codes) within the specified time range for each API, -grouped by each application. Optionally, you can configure the successAPIUsageByAppFilter parameter to further -filter the results. - -
timeFilterTimeFilter! - -The time filter. - -
successAPIUsageByAppFilterSuccessAPIUsageByAppFilter - -The successful API usage by application filter. - -
getSuccessAPIsUsageByApplicationsWithOnPremKey[SuccessAPIUsageByApplication] - -Returns a list of successful hit counts (i.e., 2xx response codes) within the specified time range for each API, -grouped by each application. Optionally, you can configure the successAPIUsageByAppFilter parameter to further -filter the results. - -
onPremKeyString! - -The value of the On-Prem key. - -
timeFilterTimeFilter! - -The time filter. - -
successAPIUsageByAppFilterSuccessAPIUsageByAppFilter - -The successful API usage by application filter. - -
getCustomReportOvertimeCustomReportOvertime - -Returns the summary of hits or latency data as specified for the selected time duration, grouped by time spans. - -
dataFilterDataFilter! - -The data filter. - -
timeFilterTimeFilter! - -The time filter. - -
metricMetric! - -The metric for which data needs to be retrieved. - -
groupByFields[GroupByField]! - -The column/field by which data needs to be retrieved. - -
groupByValues[String]! - -The value used to filter by the groupByField. - -
granularityString! - -The granularity value for which data is retrieved. - -
getCustomReportTopOvertimeCustomReportTopOvertime - -Returns the summary of hits or latency data as specified for the selected time duration, grouped by time spans for -the top N values for the selected groupByField. - -
dataFilterDataFilter! - -The data filter. - -
timeFilterTimeFilter! - -The time filter. - -
metricMetric! - -The metric for which data needs to be retrieved. - -
groupByFields[GroupByField]! - -The column/field by which the data should be grouped. - -
groupByValues[String]! - -The value used to filter by the groupByField. - -
granularityString! - -The granularity value for which data is retrieved. - -
getGroupByValues[[String]] - -Returns a list of value sets by which you can group the data available for the selected groupBy fields. - -
dataFilterDataFilter! - -The data filter. - -
groupByFields[GroupByField]! - -The column/field for which the API needs to retrieve distinct values. - -
groupByValues[String]! - -The value used to filter by the groupByField. - -
- -

Objects

-

API

-

Represents API details.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldArgumentTypeDescription
idID! - -The ID of the API. - -
nameString! - -The API name. - -
versionString! - -The API version. - -
providerString! - -The API provider name. - -
- -

APILatency

-

Represents latency values for a single API over time.

- - - - - - - - - - - - - - - - - - - - - -
FieldArgumentTypeDescription
summary[Latency] - -A list containing latency category values over time. Returns an empty array if no data is available. - -
granularityString! - -The granularity value for which data is retrieved. - -
- -

APIUsage

-

Represents the API usage for a single timestamp. The timestamp is calculated based on the granularity value provided.

- - - - - - - - - - - - - - - - - - - - - -
FieldArgumentTypeDescription
timeSpanString! - -Represents a timestamp value that is calculated based on the specified granularity value. For example, if the -granularity value is 1d, the timestamp represents the start of the day calculated adhering to the timezone -provided in the time filter. -e.g., timeSpan: '2021-06-21T00:00:00.0000000+05:30' - -
countInt! - -The API usage count. - -
- -

APIUsageByApp

-

Represents API usage across APIs by a single application.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldArgumentTypeDescription
applicationIdID! - -The application ID. - -
applicationNameString! - -The application name. - -
applicationOwnerString! - -The name of the application owner. - -
usage[APIUsage] - -A list containing the APIs usage values. Returns an empty array if no data is available. - -
- -

APIUsageByAppOverTime

-

Represents API usage across APIs by applications over time.

- - - - - - - - - - - - - - - - - - - - - -
FieldArgumentTypeDescription
usage[APIUsageByApp] - -A list containing the API usage values across APIs, grouped by the application. Returns an empty array if no data is -available. - -
granularityString! - -The granularity value for which data is retrieved. - -
- -

APIUsageByApplication

-

Represents a single API usage by a single application.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldArgumentTypeDescription
apiIdString! - -The ID of the API. - -
applicationIdString! - -The Application ID. - -
applicationNameString! - -The application name. - -
applicationOwnerString! - -The name of the application owner. - -
countInt! - -The usage of the API by the application. - -
- -

APIUsageByBackend

-

Represents API usage across APIs by a single backend.

- - - - - - - - - - - - - - - - - - - - - -
FieldArgumentTypeDescription
backendString! - -The name of the backend. - -
usage[APIUsage] - -A list containing the APIs usage values. Returns an empty array if no data is available. - -
- -

APIUsageByBackendOverTime

-

Represents API usage across APIs by each backend over time.

- - - - - - - - - - - - - - - - - - - - - -
FieldArgumentTypeDescription
usage[APIUsageByBackend] - -A list containing the API usage values across APIs by each backend. Returns an empty array if no data is available. - -
granularityString! - -The granularity value for which data is retrieved. - -
- -

APIUsageOverTime

-

Represents a single API usage over time.

- - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldArgumentTypeDescription
apiIdID - -The ID of the API. - -
usage[APIUsage] - -A list containing the API usage values. Returns an empty array if no data is available. - -
granularityString! - -The granularity value for which data is retrieved. - -
- -

AlertSummaries

-

Represents alert summaries.

- - - - - - - - - - - - - - - - - - - - - -
FieldArgumentTypeDescription
usage[AlertSummary] - -A list containing the alert summary for each alert. Returns an empty array if no data is available. - -
paginationPagination! - -The pagination details. - -
- -

AlertSummary

-

Represents a summary for an alert.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldArgumentTypeDescription
apiIdID! - -The ID of the API. - -
timestampString! - -Represents a timestamp value that is calculated based on the specified granularity value. For example, if the -granularity value is 1d, the timestamp represents the start of the day calculated adhering to the timezone -provided in the time filter. -e.g., timeSpan: '2021-06-21T00:00:00.0000000+05:30' - -
categoryString! - -The alert category. Possible values are LATENCY and TRAFFIC. - -
metricString! - -The alert metric. Possible values are RESPONSE_LATENCY and TOTAL_TRAFFIC. - -
severityString! - -The severity level of the alert. Possible values are LOW, MEDIUM, and HIGH. - -
messageString! - -The alert details. - -
- -

Application

-

Represents application details.

- - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldArgumentTypeDescription
idID! - -The Application ID. - -
nameString! - -The application name. - -
ownerString! - -The name of the application owner. - -
- -

CacheHit

-

Represents the response cache hits and misses for a single timestamp. The timestamp is calculated based on the -granularity value provided.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldArgumentTypeDescription
timeSpanString! - -Represents a timestamp value that is calculated based on the specified granularity value. For example, if the -granularity value is 1d, the timestamp represents the start of the day calculated adhering to the timezone -provided in the time filter. -e.g., timeSpan: '2021-06-21T00:00:00.0000000+05:30' - -
hitsInt! - -The number of times the response cache was hit. - -
missesInt! - -The number of times the response cache was missed. - -
hitPercentageFloat! - -The response cache hits as a percentage of the sum of hits and misses. - -
- -

CacheHits

-

Represents the response cache hits and misses over time.

- - - - - - - - - - - - - - - - - - - - - -
FieldArgumentTypeDescription
summary[CacheHit] - -A list containing cache hits, misses, and the hit percentage over time. Returns an empty array if no data is -available. - -
granularityString! - -The granularity value for which data is retrieved. - -
- -

CustomReportGroupBy

-

Represents the usage data overtime for the selected parameters of a specific groupByValue.

- - - - - - - - - - - - - - - - - - - - - -
FieldArgumentTypeDescription
groupByValueID! - -The distinct group-by value that is used as an ID. - -
usage[CustomReportUsage] - -A list containing the usage values. This returns an empty array if no data is available. - -
- -

CustomReportOvertime

-

Represents usage data overtime for the selected parameters.

- - - - - - - - - - - - - - - - - - - - - -
FieldArgumentTypeDescription
usage[CustomReportUsage] - -A list containing the usage values. This returns an empty array if no data is available. - -
granularityString! - -The granularity value for which data is retrieved. - -
- -

CustomReportTopOvertime

-

Represents usage data overtime for the selected parameters grouped by the top N groupByValues.

- - - - - - - - - - - - - - - - - - - - - -
FieldArgumentTypeDescription
usage[CustomReportGroupBy] - -A list containing the usage values grouped by the selected groupByField. This returns an empty array if no data is -available. - -
granularityString! - -The granularity value for which data is retrieved. - -
- -

CustomReportUsage

-

Represents usage data for a single timestamp in CustomReports.

- - - - - - - - - - - - - - - - - - - - - -
FieldArgumentTypeDescription
timeSpanString! - -Represents a timestamp value that is calculated based on the specified granularity value. For example, if the -granularity value is 1d, the timestamp represents the start of the day calculated adhering to the timezone -provided in the time filter. -e.g., timeSpan: '2021-06-21T00:00:00.0000000+05:30' - -
valueInt! - -The usage value (Hit Count/ Latency). - -
- -

DetailsOfErrors

-

Represents error details over time.

- - - - - - - - - - - - - - - - - - - - - -
FieldArgumentTypeDescription
usage[ErrorDetails]! - -A list containing error details over time. Returns an empty array if no data is available. - -
paginationPagination! - -The pagination details. - -
- -

Environment

-

Represents an environment.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldArgumentTypeDescription
idString! - -The environment ID. - -
externalEnvIdString! - -The external environment ID. - -
internalEnvIdString - -The internal environment ID. - -
sandboxEnvIdString - -The sandbox environment ID. - -
nameString! - -The environment name. - -
typeEnvironmentType! - -The environment type. A Choreo environment is labeled as CHOREO, a private Choreo environment is labeled as -CHOREO_PRIVATE, and the on-premise environment is labeled as ON_PREM. - -
- -

ErrorCountByCategory

-

Represents the number of errors from each category for a single timestamp. The timestamp is calculated according to the -provided granularity value. If you select some categories, the error counts are retrieved only for those categories, -and a null value is shown for the other categories that are not selected.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldArgumentTypeDescription
timeSpanString! - -Represents a timestamp value that is calculated based on the specified granularity value. For example, if the -granularity value is 1d, the timestamp represents the start of the day calculated adhering to the timezone -provided in the time filter. -e.g., timeSpan: '2021-06-21T00:00:00.0000000+05:30' - -
authInt - -The count of authorization errors. - -
targetConnectivityInt - -The count of target connectivity errors. - -
throttledInt - -The count of throttling errors. - -
otherInt - -The count of other errors. - -
- -

ErrorCountByCode

-

Represents the error count for a single error status code.

- - - - - - - - - - - - - - - - - - - - - -
FieldArgumentTypeDescription
statusCodeString! - -The error status code. - -
countInt! - -The error count. - -
- -

ErrorCountByCodeForAPI

-

Represents the error count for each status code for a single API.

- - - - - - - - - - - - - - - - - - - - - -
FieldArgumentTypeDescription
apiIdID! - -The ID of the API. - -
errorCountByCode[ErrorCountByCode] - -A list containing the error count for each error status code. Returns an empty array if no data is available. - -
- -

ErrorDetails

-

Represents details of an error for a single timestamp. The timestamp is calculated according to the granularity value -provided.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldArgumentTypeDescription
apiIdID - -The ID of the API. - -
timeSpanString! - -Represents a timestamp value that is calculated based on the specified granularity value. For example, if the -granularity value is 1d, the timestamp represents the start of the day calculated adhering to the timezone -provided in the time filter. -e.g., timeSpan: '2021-06-21T00:00:00.0000000+05:30' - -
applicationIdString - -The Application ID. - -
applicationNameString - -The application name. - -
applicationOwnerString - -The name of the application owner. - -
reasonString! - -The reason for the error. - -
countInt! - -The error count. - -
- -

ErrorStatusCodeCategoryCounts

-

Represents errors by the main status code (4xx or 5xx) and the total error count.

- - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldArgumentTypeDescription
_4xxInt - -The number of client errors. - -
_5xxInt - -The number of server errors. - -
totalInt - -The total number of client and server errors. - -
- -

ErrorSummary

-

Provides the unsuccessful usage (i.e., 4xx and 5xx response codes) summary across all APIs.

- - - - - - - - - - - - - - - - - - - - - -
FieldArgumentTypeDescription
summary[ErrorValue]! - -A list containing unsuccessful usage values. Returns an empty array if no data is available. - -
granularityString! - -The granularity value for which data is retrieved. - -
- -

ErrorValue

-

Represents the unsuccessful request count (i.e., 4xx and 5xx response codes) for a single timestamp. The timestamp -is calculated based on the granularity value provided.

- - - - - - - - - - - - - - - - - - - - - -
FieldArgumentTypeDescription
timeSpanString - -Represents a timestamp value that is calculated based on the specified granularity value. For example, if the -granularity value is 1d, the timestamp represents the start of the day calculated adhering to the timezone -provided in the time filter. -e.g., timeSpan: '2021-06-21T00:00:00.0000000+05:30' - -
errorCountInt - -Represents the error request count. - -
- -

ErrorsByCategory

-

Represents the errors by category over time.

- - - - - - - - - - - - - - - - - - - - - -
FieldArgumentTypeDescription
errors[ErrorCountByCategory] - -A list containing the error count for each error category over time. Returns an empty array if no data is available. - -
granularityString! - -The granularity value for which data is retrieved. - -
- -

ErrorsByStatusCode

-

Represents the error counts grouped by status code for each API.

- - - - - - - - - - - - - - - - - - - - - -
FieldArgumentTypeDescription
errors[ErrorCountByCodeForAPI]! - -A list containing the error count for each status code for each API. Returns an empty array if no data is available. - -
paginationPagination! - -Pagination details. - -
- -

ErrorsByStatusCodeCategory

-

Represents the error category values (grouped as 4xx, 5xx, and total) for both proxy and target errors for a -single timestamp. The timestamp is calculated based on the granularity value provided.

- - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldArgumentTypeDescription
timeSpanString! - -Represents a timestamp value that is calculated based on the specified granularity value. For example, if the -granularity value is 1d, the timestamp represents the start of the day calculated adhering to the timezone -provided in the time filter. -e.g., timeSpan: '2021-06-21T00:00:00.0000000+05:30' - -
proxyErrorStatusCodeCategoryCounts - -Represents proxy-related errors categorized as client errors (4xx response codes) or server errors (5xx response -codes), and the total of both categories. - -
targetErrorStatusCodeCategoryCounts - -Represents target-related errors categorized as client errors (4xx response codes) or server errors (5xx -response codes), and the total of both categories. - -
- -

Latency

-

Represents latency values for each latency category for a single timestamp. The timestamp is calculated based on the -granularity value provided.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldArgumentTypeDescription
timeSpanString - -Represents a timestamp value that is calculated based on the specified granularity value. For example, if the -granularity value is 1d, the timestamp represents the start of the day calculated adhering to the timezone -provided in the time filter. -e.g., timeSpan: '2021-06-21T00:00:00.0000000+05:30' - -
responseInt - -The response latency (95th percentile) in milliseconds (ms). - -
backendInt - -The backend latency (95th percentile) in milliseconds (ms). - -
requestMediationInt - -The request mediation latency (95th percentile) in milliseconds (ms). - -
responseMediationInt - -The response mediation latency (95th percentile) in milliseconds (ms). - -
responseMedianInt - -The median (50th percentile) of the response latency in milliseconds (ms). - -
backendMedianInt - -The median (50th percentile) of the backend latency in milliseconds (ms). - -
requestMediationMedianInt - -The median (50th percentile) of the request mediation latency in milliseconds (ms). - -
responseMediationMedianInt - -The median (50th percentile) of the response mediation latency in milliseconds (ms). - -
- -

LatencySummary

-

Provides the latency summary.

- - - - - - - - - - - - - - - - - - - - - -
FieldArgumentTypeDescription
summary[LatencyValue]! - -A list containing latency values. Returns an empty array if no data is available. - -
granularityString! - -The granularity value for which data is retrieved. - -
- -

LatencyValue

-

Represents the latency value for a single timestamp. The timestamp is calculated according to the provided granularity -value.

- - - - - - - - - - - - - - - - - - - - - -
FieldArgumentTypeDescription
timeSpanString! - -Represents a timestamp value that is calculated based on the specified granularity value. For example, if the -granularity value is 1d, the timestamp represents the start of the day calculated adhering to the timezone -provided in the time filter. -e.g., timeSpan: '2021-06-21T00:00:00.0000000+05:30' - -
latencyTimeFloat! - -Represents the latency (95th percentile) time in milliseconds (ms). - -
- -

Organization

-

Represents an organization.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldArgumentTypeDescription
idString! - -The organization ID. - -
uuidID! - -The organization UUID. - -
handleString! - -The organization handle name. - -
nameString! - -The organization name. - -
- -

OverallLatency

-

Represents the overall latency values.

- - - - - - - - - - - - - - - - -
FieldArgumentTypeDescription
responseFloat - -The response latency (95th percentile value) in milliseconds (ms). - -
- -

Pagination

-

Represents pagination details.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldArgumentTypeDescription
totalInt! - -The total number of results. - -
limitInt! - -The number of items in the result set. - -
offsetInt! - -The offset value for the result set. - -
sortByString! - -The sorting column name of the result set. - -
sortOrderString! - -The sorting order of the result set. Possible values are asc and desc. - -
- -

Platform

-

Represents a platform.

- - - - - - - - - - - - - - - - - - - - - -
FieldArgumentTypeDescription
platformString! - -The name of the platform. - -
countInt! - -The usage of the platform. - -
- -

Provider

-

Represents API Provider details.

- - - - - - - - - - - - - - - - -
FieldArgumentTypeDescription
nameString! - -The API provider name. - -
- -

ResourceUsage

-

Represents the usage of a single API resource.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldArgumentTypeDescription
apiIdID! - -The ID of the API. - -
apiResourceTemplateString! - -The API resource template. - -
apiMethodString! - -The API method. - -
countInt! - -The usage of the API resource. - -
- -

ResourceUsages

-

Represents API resource usages.

- - - - - - - - - - - - - - - - - - - - - -
FieldArgumentTypeDescription
usage[ResourceUsage] - -A list with the usage of each API resource. Returns an empty array if no data is available. - -
paginationPagination! - -Pagination details. - -
- -

SlowAPI

-

A slow API identified based on the response latency (95th percentile).

- - - - - - - - - - - - - - - - - - - - - -
FieldArgumentTypeDescription
apiIdID! - -The ID of the API. - -
latencyInt! - -Represents the latency (95th percentile) time in milliseconds (ms). - -
- -

Subscriber

-

Represents API Subscriber details.

- - - - - - - - - - - - - - - - -
FieldArgumentTypeDescription
nameString! - -The name of the API subscriber. - -
- -

SuccessAPIUsageByApplication

-

Represents successful usages(that have resulted in the 2xx response code) of an API by an application.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldArgumentTypeDescription
apiIdString! - -The ID of the API. - -
apiNameString! - -The name of the API. - -
apiVersionString! - -The version of the API. - -
apiCreatorTenantDomainString! - -The tenant domain of the API creator. - -
applicationIdString! - -The application ID. - -
applicationNameString! - -The name of the application. - -
applicationOwnerString! - -The name of the application owner. - -
countInt!
- -

SuccessSummary

-

Provides the successful (2xx response code) usage summary across all the APIs.

- - - - - - - - - - - - - - - - - - - - - -
FieldArgumentTypeDescription
summary[SuccessValue]! - -A list containing successful usage values. Returns an empty array if no data is available. - -
granularityString! - -The granularity value for which data is retrieved. - -
- -

SuccessValue

-

Represents the successful request count (i.e., requests that have received the 2xx response code) for a single -timestamp. The timestamp is calculated according to the granularity value provided.

- - - - - - - - - - - - - - - - - - - - - -
FieldArgumentTypeDescription
timeSpanString! - -Represents a timestamp value that is calculated based on the specified granularity value. For example, if the -granularity value is 1d, the timestamp represents the start of the day calculated adhering to the timezone -provided in the time filter. -e.g., timeSpan: '2021-06-21T00:00:00.0000000+05:30' - -
requestCountInt! - -Represents the successful request count. - -
- -

TopAPIByAlertCount

-

Represents a top API by alert count.

- - - - - - - - - - - - - - - - - - - - - -
FieldArgumentTypeDescription
apiIdID! - -The ID of the API. - -
countInt! - -The alert count. - -
- -

TopAPIsByAlertCount

-

Represents the top APIs by alert count.

- - - - - - - - - - - - - - - - - - - - - -
FieldArgumentTypeDescription
usage[TopAPIByAlertCount] - -A list containing top APIs by alert count. Returns an empty array if no data is available. - -
paginationPagination! - -The pagination details. - -
- -

TotalError

-

Represents the total errors.

- - - - - - - - - - - - - - - - -
FieldArgumentTypeDescription
proxyInt - -The proxy-related error count. - -
- -

UsageByGeoLocation

-

Represents the usage of a single API in a single country.

- - - - - - - - - - - - - - - - - - - - - -
FieldArgumentTypeDescription
countryString! - -The name of the country. - -
countInt! - -The usage of the API. - -
- -

UserAgent

-

Represents a user agent.

- - - - - - - - - - - - - - - - - - - - - -
FieldArgumentTypeDescription
userAgentString! - -The name of the user agent. - -
countInt! - -The usage of the user agent. - -
- -

Inputs

-

APIUsageByAppFilter

-

Filters the API usage by application results.

- - - - - - - - - - - - - - - - - - - - - - - - - -
FieldTypeDescription
apiIds[String] - -The results are filtered for the list of APIs you specify here. A maximum of five API IDs can be defined. - -
appIds[String] - -The results are filtered for the list of applications you specify here. A maximum of five application IDs can be -defined. - -
subscribers[String] - -The results are filtered for the list of subscribers you specify here. A maximum of five subscriber IDs can be -defined. - -
- -

APIUsageByBackendOverTimeFilter

-

Filters the results for API usage by backend over time.

- - - - - - - - - - - - - - - - - - - - -
FieldTypeDescription
apiIds[String] - -The results are filtered for the list of APIs you specify here. A maximum of five API IDs can be defined. - -
granularityString - -The granularity value that is used for data retrieval. If the granularity value is not set, the default granularity -for the related time range is applied. The possible granularity values that you can specify are 1m, 15m, 1h, -1d, and 7d. - -
- -

APIUsageOverTimeFilter

-

Filters the results for API usage over time.

- - - - - - - - - - - - - - - - - - - - - - - - - -
FieldTypeDescription
apiIds[String] - -The results are filtered for the list of APIs you specify here. A maximum of five API IDs can be defined. - -
appIds[String] - -The results are filtered for the list of applications you specify here. A maximum of five application IDs can be -defined. - -
granularityString - -The granularity value that is used for data retrieval. If the granularity value is not set, the default granularity -for the related time range is applied. The possible granularity values that you can specify are 1m, 15m, 1h, -1d, and 7d. - -
- -

AlertSummaryFilter

-

Filters the alerts summary results.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldTypeDescription
paginationFilterPaginationFilter - -The pagination filter. - -
searchFilterSearchFilter - -The search filter. - -
apiIds[String] - -The results are filtered for the list of APIs you specify here. A maximum of five API IDs can be defined. - -
categoryString - -The alert category by which the results need to be filtered. The available categories to select are TRAFFIC and -LATENCY. - -
- -

ApplicationFilter

-

Filters applications by the application owner and API IDs.

- - - - - - - - - - - - - - - - - - - - -
FieldTypeDescription
ownerString
apiIds[String] - -The results are filtered for the list of APIs you specify here. A maximum of five API IDs can be defined. - -
- -

CacheFilter

-

Filters response cache results.

- - - - - - - - - - - - - - - - - - - - -
FieldTypeDescription
apiIdString - -The results are filtered by the API ID specified here. - -
granularityString - -The granularity value that is used for data retrieval. If the granularity value is not set, the default granularity -for the related time range is applied. The possible granularity values that you can specify are 1m, 15m, 1h, -1d, and 7d. - -
- -

DataFilter

-

Filters results by the given combination of organization, environment, and tenant.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldTypeDescription
orgIdString! - -The organization by which the results need to be filtered. It is required to specify a value for this parameter. - -
environmentIdString - -The environment ID by which the results need to be filtered. It is required to specify a value for this parameter. - -
environmentIds[String] - -The environment IDs by which the results need to be filtered. It is required to specify a value for this parameter. - -
tenantString! - -The name of the tenant by which the results need to be filtered. It is required to specify a value for this -parameter. - -
projectIdString - -The project ID by which the results need to be filtered. It is optional to specify a value for this -parameter. Note that providing a project ID with an on-prem key is not allowed. - -
- -

DeviceFilter

-

Filters results related to devices.

- - - - - - - - - - - - - - - -
FieldTypeDescription
apiIds[String] - -The results are filtered for the list of APIs you specify here. A maximum of five API IDs can be defined. - -
- -

ErrorCountByStatusCodeFilter

-

Filters errors by status code results.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldTypeDescription
apiIdString - -The results are filtered by the API ID specified here. - -
errorTypeErrorType! - -The type of the error. It is required to specify a value for this parameter. - -
errorCodeTypeErrorCodeType - -The error code type. If this parameter is not configured, both client-related error response codes (401, 404, -etc.) and server-related response codes (500, 501, etc.) are included in the result set. - -
paginationFilterPaginationFilter - -The pagination filter. - -
- -

ErrorsByCategoryFilter

-

Filters errors by category results.

- - - - - - - - - - - - - - - - - - - - - - - - - -
FieldTypeDescription
apiIdString - -The ID of the API. - -
categories[String] - -The list of categories by which the results need to be filtered. Category values that you can specify here are -AUTH, TARGET_CONNECTIVITY, THROTTLED, and OTHER. - -
granularityString - -The granularity value that is used for data retrieval. If the granularity value is not set, the default granularity -for the related time range is applied. The possible granularity values that you can specify are 1m, 15m, 1h, -1d, and 7d. - -
- -

ErrorsByStatusCodeFilter

-

Filters errors by status code results.

- - - - - - - - - - - - - - - - - - - - -
FieldTypeDescription
apiIdString - -The results are filtered by the API ID specified here. - -
granularityString - -The granularity value that is used for data retrieval. If the granularity value is not set, the default granularity -for the related time range is applied. The possible granularity values that you can specify are 1m, 15m, 1h, -1d, and 7d. - -
- -

ErrorsDetailsFilter

-

Filters the results for error details.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldTypeDescription
apiIdString - -The results are filtered by the API ID specified here. - -
appIdString - -The application ID by which the results need to be filtered. - -
categoryString - -The error category by which the results need to be filtered. The error category that you can specify here must be -one of the AUTH TARGET_CONNECTIVITY, THROTTLED, and OTHER values. - -
granularityString - -The granularity value that is used for data retrieval. If the granularity value is not set, the default granularity -for the related time range is applied. The possible granularity values that you can specify are 1m, 15m, 1h, -1d, and 7d. - -
paginationFilterPaginationFilter - -The pagination filter. - -
searchFilterSearchFilter - -The search filter. - -
- -

GeoLocationFilter

-

Filters the API usage by geolocation results.

- - - - - - - - - - - - - - - -
FieldTypeDescription
apiIds[String] - -The results are filtered for the list of APIs you specify here. - -
- -

LatencyFilter

-

Filters latency results.

- - - - - - - - - - - - - - - - - - - - -
FieldTypeDescription
apiIdString! - -The results are filtered by the API ID specified here. It is required to specify a value for this parameter. - -
granularityString - -The granularity value that is used for data retrieval. If the granularity value is not set, the default granularity -for the related time range is applied. The possible granularity values that you can specify are 1m, 15m, 1h, -1d, and 7d. - -
- -

LatencySummaryFilter

-

Filters latency summary results.

- - - - - - - - - - - - - - - - - - - - -
FieldTypeDescription
apiIdString - -The results are filtered by the API ID specified here. - -
granularityString - -The granularity value that is used for data retrieval. If the granularity value is not set, the default granularity -for the related time range is applied. The possible granularity values that you can specify are 1m, 15m, 1h, -1d, and 7d. - -
- -

OrgFilter

-

Filters results for the given organization.

- - - - - - - - - - - - - - - -
FieldTypeDescription
orgIdString! - -The ID of the organization by which the results need to be filtered. It is required to specify a value for this -parameter. - -
- -

PaginationFilter

-

Filters related to pagination.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldTypeDescription
limitInt - -The total number of rows in the result set. This value must be a positive integer. If this limit value is not set, -the total number of rows is five by default. - -
offsetInt - -The offset value to set when filtering results. This value must be zero or a positive integer. If you do not specify -an offset value, the default offset value (i.e., 0) applies. - -
sortByString - -The column name by which the results are sorted. If the sortBy value is not set, the default column of the related -operation that is available for sorting purposes is used. - -
sortOrderString - -The order in which the results are sorted. Possible values are asc (to sort in ascending order) and desc (to -sort in descending order). If no value is specified, the results are sorted in ascending order by default (except -for count-specific operations such as getTopAPIsByAlertCount where the results are always sorted in descending -order). - -
- -

ResourceUsageFilter

-

Filters resource usage results.

- - - - - - - - - - - - - - - - - - - - -
FieldTypeDescription
paginationFilterPaginationFilter - -The pagination filter. - -
searchFilterSearchFilter - -The search filter. - -
- -

SearchFilter

-

Filters results by searching matching results for the provided search text.

- - - - - - - - - - - - - - - - - - - - -
FieldTypeDescription
apiIds[String] - -The list of API IDs that need to be searched with the given search text. Note that it is not possible to define API -IDs without a search text in the search filter. - -
searchTextString! - -Text which needs to be searched among the results. It is required to specify a value for this parameter. - -
- -

SubscriberFilter

-

Filters the subscriber results.

- - - - - - - - - - - - - - - -
FieldTypeDescription
apiIds[String] - -The results are filtered for the list of APIs you specify here. A maximum of five API IDs can be defined. - -
- -

SuccessAPIUsageByAppFilter

-

Filters successful API usage by application results.

- - - - - - - - - - - - - - - - - - - - -
FieldTypeDescription
apiIds[String] - -The list of API IDs by which the results need to be filtered. - -
tenantDomains[String] - -The tenant domain name by which the results need to be filtered. - -
- -

TenantDataFilter

-

Filters results by the tenant.

- - - - - - - - - - - - - - - - - - - - - - - - - -
FieldTypeDescription
orgIdString! - -The ID of the organization by which the results need to be filtered. It is required to specify a value for this -parameter. - -
envIdString - -The ID of the environment by which the results need to be filtered. It is required to specify a value for this -parameter. - -
environmentIds[String] - -The environment IDs by which the results need to be filtered. It is required to specify a value for this parameter. - -
- -

TimeFilter

-

Filters results by the provided date range.

- - - - - - - - - - - - - - - - - - - - -
FieldTypeDescription
fromString! - -The start date of the time range. The date specified here must be a date earlier than the date specified via the -to parameter. If the defined date and time entry do not have a timezone, the UTC time zone (z) is used. It is -required to specify a value for this parameter. -e.g., '2021-08-16T12:00:00.000+05:30'. - -
toString! - -The end date of the time range. The date specified here must be a date later than the date specified via the from -parameter. If the defined date and time entry do not have a timezone, the UTC time zone (z) is used. It is -required to specify a value for this parameter. -e.g., '2021-08-16T12:30:00.000+05:30'. - -
- -

TopAPIsByAlertCountFilter

-

Filters the top APIs by alert count results.

- - - - - - - - - - - - - - - - - - - - -
FieldTypeDescription
paginationFilterPaginationFilter - -The pagination filter. - -
searchFilterSearchFilter - -The search filter. - -
- -

Enums

-

EnvironmentType

-

Represents an error type.

- - - - - - - - - - - - - - - - - - - -
ValueDescription
CHOREO - -The Choreo environments. - -
CHOREO_PRIVATE - -The private data-plane Choreo environments. - -
ON_PREM - -The On-Premise environments. - -
- -

ErrorCodeType

-

Represents an error code type.

- - - - - - - - - - - - - - - -
ValueDescription
_4XX - -The client-side errors. - -
_5XX - -The server-side errors. - -
- -

ErrorType

-

Represents an error type.

- - - - - - - - - - - - - - - -
ValueDescription
PROXY - -The proxy-related errors. - -
TARGET - -The target-related errors. - -
- -

GroupByField

-

Represents an groupByField used in CustomReports.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
ValueDescription
API_NAME - -The API name. - -
API_VERSION - -The API version. - -
API_RESOURCE_TEMPLATE - -The API resource template. - -
API_METHOD - -The API method. - -
API_CREATOR - -The API creator. - -
APPLICATION_NAME - -The name of the application. - -
APPLICATION_OWNER - -The owner of the application. - -
DESTINATION - -The destination. - -
USER_AGENT - -The user Agent. - -
PLATFORM - -The platform. - -
TARGET_RESPONSE_CODE - -The target response code. - -
- -

Metric

-

Represents a metric used in CustomReports.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
ValueDescription
HIT_COUNT - -The number of API calls. - -
RESPONSE_CACHE_HIT - -The number of API calls that used the response cache. - -
REQUEST_MEDIATION_LATENCY - -The request mediation latency. - -
RESPONSE_MEDIATION_LATENCY - -The response mediation latency. - -
BACKEND_LATENCY - -The backend latency. - -
TOTAL_LATENCY - -The total latency. - -
API_ERRORS - -The number of hits for which API errors are returned. - -
TARGET_ERRORS - -The number of hits for which target errors are returned. - -
- -

Scalars

-

Boolean

-

The Boolean scalar type represents true or false.

-

Float

-

The Float scalar type represents signed double-precision fractional values as specified by IEEE 754.

-

ID

-

The ID scalar type represents a unique identifier, often used to re-fetch an object or as the key for a cache. The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When expected as an input type, any string (such as "4") or integer (such as 4) input value is accepted as an ID.

-

Int

-

The Int scalar type represents non-fractional signed whole numeric values. Int can represent values between -(2^31) and 2^31 - 1.

-

String

-

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

- - - - - - -
-
- - -
- - - -
- - -
- - - -
-
-
- - - - - - - - - - - - - - - - - \ No newline at end of file diff --git a/en/site/observability/observability-overview/index.html b/en/site/observability/observability-overview/index.html deleted file mode 100644 index 940083989..000000000 --- a/en/site/observability/observability-overview/index.html +++ /dev/null @@ -1,15 +0,0 @@ - - - - - - Redirecting... - - - - - - -Redirecting... - - diff --git a/en/site/observability/root-cause-analysis/index.html b/en/site/observability/root-cause-analysis/index.html deleted file mode 100644 index 80ba06a26..000000000 --- a/en/site/observability/root-cause-analysis/index.html +++ /dev/null @@ -1,15 +0,0 @@ - - - - - - Redirecting... - - - - - - -Redirecting... - - diff --git a/en/site/observe-and-analyze/analyze/choreo-insights-api/index.html b/en/site/observe-and-analyze/analyze/choreo-insights-api/index.html deleted file mode 100644 index 9347b189d..000000000 --- a/en/site/observe-and-analyze/analyze/choreo-insights-api/index.html +++ /dev/null @@ -1,15 +0,0 @@ - - - - - - Redirecting... - - - - - - -Redirecting... - - diff --git a/en/site/observe-and-analyze/analyze/configure-alerts/index.html b/en/site/observe-and-analyze/analyze/configure-alerts/index.html deleted file mode 100644 index 17db144ab..000000000 --- a/en/site/observe-and-analyze/analyze/configure-alerts/index.html +++ /dev/null @@ -1,15 +0,0 @@ - - - - - - Redirecting... - - - - - - -Redirecting... - - diff --git a/en/site/observe-and-analyze/analyze/dora-metrics/configure-cio-dashboard/index.html b/en/site/observe-and-analyze/analyze/dora-metrics/configure-cio-dashboard/index.html deleted file mode 100644 index 649f91f47..000000000 --- a/en/site/observe-and-analyze/analyze/dora-metrics/configure-cio-dashboard/index.html +++ /dev/null @@ -1,15 +0,0 @@ - - - - - - Redirecting... - - - - - - -Redirecting... - - diff --git a/en/site/observe-and-analyze/analyze/dora-metrics/view-dora-metrics/index.html b/en/site/observe-and-analyze/analyze/dora-metrics/view-dora-metrics/index.html deleted file mode 100644 index 7974d4a0b..000000000 --- a/en/site/observe-and-analyze/analyze/dora-metrics/view-dora-metrics/index.html +++ /dev/null @@ -1,15 +0,0 @@ - - - - - - Redirecting... - - - - - - -Redirecting... - - diff --git a/en/site/observe-and-analyze/analyze/generate-custom-reports/index.html b/en/site/observe-and-analyze/analyze/generate-custom-reports/index.html deleted file mode 100644 index 25ca54f22..000000000 --- a/en/site/observe-and-analyze/analyze/generate-custom-reports/index.html +++ /dev/null @@ -1,15 +0,0 @@ - - - - - - Redirecting... - - - - - - -Redirecting... - - diff --git a/en/site/observe-and-analyze/analyze/programmatic-access-choreo-insights-api/index.html b/en/site/observe-and-analyze/analyze/programmatic-access-choreo-insights-api/index.html deleted file mode 100644 index a524c8f81..000000000 --- a/en/site/observe-and-analyze/analyze/programmatic-access-choreo-insights-api/index.html +++ /dev/null @@ -1,15 +0,0 @@ - - - - - - Redirecting... - - - - - - -Redirecting... - - diff --git a/en/site/observe-and-analyze/analyze/view-api-insights/index.html b/en/site/observe-and-analyze/analyze/view-api-insights/index.html deleted file mode 100644 index 9023b18e2..000000000 --- a/en/site/observe-and-analyze/analyze/view-api-insights/index.html +++ /dev/null @@ -1,15 +0,0 @@ - - - - - - Redirecting... - - - - - - -Redirecting... - - diff --git a/en/site/observe-and-analyze/observe/observability-overview/index.html b/en/site/observe-and-analyze/observe/observability-overview/index.html deleted file mode 100644 index 5bf45b44e..000000000 --- a/en/site/observe-and-analyze/observe/observability-overview/index.html +++ /dev/null @@ -1,15 +0,0 @@ - - - - - - Redirecting... - - - - - - -Redirecting... - - diff --git a/en/site/observe-and-analyze/observe/root-cause-analysis/index.html b/en/site/observe-and-analyze/observe/root-cause-analysis/index.html deleted file mode 100644 index 01f424356..000000000 --- a/en/site/observe-and-analyze/observe/root-cause-analysis/index.html +++ /dev/null @@ -1,15 +0,0 @@ - - - - - - Redirecting... - - - - - - -Redirecting... - - diff --git a/en/site/page-not-found/index.html b/en/site/page-not-found/index.html deleted file mode 100644 index 2ae0fc7ef..000000000 --- a/en/site/page-not-found/index.html +++ /dev/null @@ -1,3053 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - Page not found - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
-
- - - -
- - - - - - -
- - -
- -
- - - - - - - -
-
- - - -
-
-
- - - - -
-
-
- - - -
-
-
- - - -
-
-
- - - -
-
- - - - - - - - - - - - - - - - - - - - -

Page not found

- - - -

Try one of the navigation links above or use the search engine in the top right corner. 

- - - - - - -
-
- - -
- - - -
- - -
- -
-
-
-
- Copyright © WSO2 LLC (2023-2024) -
-
- Content licensed under CC By 4.0. | Sample code - licensed under Apache 2.0. -
-
-
-
-
- - - -
-
-
- - - - - - - - - - - - - - - - - \ No newline at end of file diff --git a/en/site/quick-start-guides/build-your-first-cloud-native-application-with-choreo/index.html b/en/site/quick-start-guides/build-your-first-cloud-native-application-with-choreo/index.html deleted file mode 100644 index 1bab0eb3b..000000000 --- a/en/site/quick-start-guides/build-your-first-cloud-native-application-with-choreo/index.html +++ /dev/null @@ -1,15 +0,0 @@ - - - - - - Redirecting... - - - - - - -Redirecting... - - diff --git a/en/site/quick-start-guides/build-your-first-integration-with-choreo-ipaas/index.html b/en/site/quick-start-guides/build-your-first-integration-with-choreo-ipaas/index.html deleted file mode 100644 index 1379409c4..000000000 --- a/en/site/quick-start-guides/build-your-first-integration-with-choreo-ipaas/index.html +++ /dev/null @@ -1,15 +0,0 @@ - - - - - - Redirecting... - - - - - - -Redirecting... - - diff --git a/en/site/quick-start-guides/deploy-a-web-application-that-consumes-a-backend-service/index.html b/en/site/quick-start-guides/deploy-a-web-application-that-consumes-a-backend-service/index.html deleted file mode 100644 index 71c0b27bf..000000000 --- a/en/site/quick-start-guides/deploy-a-web-application-that-consumes-a-backend-service/index.html +++ /dev/null @@ -1,3810 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - Deploy a Web Application that Consumes a Backend Service - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- - - -
- - - - - - -
- - -
- -
- - - - - - - -
-
- - - -
-
-
- - - - -
-
-
- - - -
-
-
- - - -
-
-
- - - -
-
- - - - - - - - - - - - - - - - - - - - -

Deploy a Web Application that Consumes a Backend Service

-

Choreo is an Internal Developer Platform (IDevP) that streamlines the entire process of building, deploying, monitoring, and managing your cloud-native applications easily.

-

In this quick start guide, you will explore how to expose a service endpoint via Choreo and securely consume the service from a web application. You will use a simple reading list web application with a sign-in page and functionality to interact with a secure backend service. You will also use Choreo's managed authentication to easily set up authentication for your web application without having to dive into the details of security protocols. The application will allow users to sign in and view their reading lists, add books to a reading list, delete books from the reading list, and sign out of the application effortlessly.

-

This guide walks you through the following steps:

-
    -
  • Deploy and test a service component.
    • -
  • Create a web application to consume the exposed service.
    • -
  • Create a connection to the deployed service.
    • -
  • Enable managed authentication and deploy the web application.
    • -
  • Consume the deployed service via the web application.
    • -
-

Prerequisites

-

Before you try out this guide, complete the following:

-
    -
  1. -

    Create a GitHub repository to save the service implementation. For this guide, you can fork the Choreo sample book list app repository.

    -
    2. -
  2. -

    If you are signing in to the Choreo Console for the first time, create an organization as follows:

    -
      -
    1. Go to https://console.choreo.dev/, and sign in using your Google, GitHub, or Microsoft account.
      2. -
    2. Enter a unique organization name. For example, Stark Industries.
      3. -
    3. Read and accept the privacy policy and terms of use.
      4. -
    4. Click Create.
      5. -
    -

    This creates the organization and opens the organization home page.

    -
    3. -
-

Step 1: Create a project

-

Follow the steps given below to create a project:

-
    -
  1. Go to https://console.choreo.dev/ and sign in. This opens the organization home page.
    2. -
  2. On the organization home page, click + Create Project.
    3. -
  3. -

    Enter a display name, unique name, and description for the project. You can enter the values given below:

    -
    -

    Tip

    -

    In the Name field, you must specify a name to uniquely identify your project in various contexts. The value is editable only at the time you create the project. You cannot change the name after you create the project.

    -
    - - - - - - - - - - - - - - - - - - - - - -
    FieldValue
    Project Display NameSample project
    Namesample-project
    Project DescriptionMy sample project
    -
    4. -
  4. -

    Click Create. This creates the project and opens the project home page.

    -
    5. -
-

Step 2: Connect your sample repository and configure the sample service

-

To connect to the repository you forked in the prerequisites and configure the sample service, follow the steps given below:

-
    -
  1. On the project home page, click Start under Create Multiple Components.
    2. -
  2. Go to the GitHub tab.
    3. -
  3. -

    To allow Choreo to connect to your GitHub account, click Authorize with GitHub. If you have not already connected your GitHub repository to Choreo, enter your GitHub credentials and select the repository you created in the prerequisites section to install the Choreo GitHub App.

    -

    Alternatively, you can paste the Choreo sample book list app repository URL in the Provide Repository URL field to connect to it without requiring authorization from the Choreo Apps GitHub application. However, authorizing the repository with the Choreo GitHub App is necessary if you want to enable Auto Deploy for the component.

    -
    -

    Note

    -

    The Choreo GitHub App requires the following permissions:

    -
      -
    • Read and write access to code and pull requests.
      • -
    • Read access to issues and metadata.
      • -
    -

    You can revoke access if you do not want Choreo to have access to your GitHub account. However, write access is exclusively utilized for sending pull requests to a user repository. Choreo will not directly push any changes to a repository.

    -
    -
    4. -
  4. -

    Enter the following information:

    - - - - - - - - - - - - - - - - - - - - - -
    FieldValue
    OrganizationYour GitHub account
    Repositorychoreo-sample-book-list-app
    Branchmain
    -
    5. -
  5. -

    In the Add Component Directories pane under Configure Components, click the + icon corresponding to reading-list-service.

    -
    6. -
  6. -

    In the Component Configuration dialog that opens, specify values as follows for each of the fields:

    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    FieldValue
    Component Display NameReading List Service
    Component Namereading-list-service
    Pathreading-list-service
    Component TypeService
    BuildpackNodeJS
    Language Version20.x.x
    -
    7. -
  7. -

    Click Save. This adds the Reading List Service component to the Configured Components pane.

    -
    8. -
  8. -

    Click Finish. This initializes the service with the implementation from your GitHub repository and takes you to the project home page.

    -

    You can see the Reading List Service component listed under Component Listing on the project home page.

    -
    9. -
-

Step 3: Build the service

-

To build the service, follow the steps given below:

-
    -
  1. On the project home page, click the Reading List Service component listed under Component Listing. This takes you to the component overview page.
    2. -
  2. In the left navigation menu, click Build.
    3. -
  3. In the Builds pane, click Build Latest.
    4. -
-

!!! note - Building the service component may take a while. You can track the progress via the logs in the Build Details pane. Once the build process is complete, the build status changes to Success.

-

Step 4: Deploy the service

-

For the REST endpoint of the service to be invokable, you need to deploy it. To deploy the service, follow the steps given below:

-
    -
  1. In the left navigation menu, click Deploy.
    2. -
  2. In the Set Up card, click Configure & Deploy.
    3. -
  3. In the Environment Configurations pane that opens, click Next to skip the configuration.
    4. -
  4. In the File Mount pane that opens, click Next to skip the configuration.
    5. -
  5. In the Endpoint Details pane that opens, verify that the Network Visibility is set to Public. This setting securely exposes the endpoint for consumption.
    6. -
  6. Click Deploy. This deploys the service to the development environment and lists the service in the Choreo Marketplace.
    7. -
-

Step 5: Test the service

-

To test the endpoint via the integrated OpenAPI Console in Choreo, follow the steps given below:

-
    -
  1. In the Choreo Console left navigation menu, click Test and then click Console.
    2. -
  2. In the OpenAPI Console that opens, select Development from the environment drop-down list.
    3. -
  3. In the Endpoint list, select Books REST Endpoint.
    4. -
  4. Expand the GET/books method, click Try it out, then click Execute.
    5. -
  5. Click .
    6. -
  6. Check the Server Response section. You will see an empty response. You can add an entry using the POST method and retry the GET/books method again.
    7. -
  7. Expand the POST/books method and click Try it out.
    8. -
  8. -

    Update the request body so that the parameters have the values given below:

    - - - - - - - - - - - - - - - - - - - - - -
    ParameterValue
    authorBram Stoker
    statusto_read
    titleDracula
    -

    The request body should look as follows:

    -

      {
-    "author": "Bram Stoker",
-    "status": "to_read",
-    "title": "Dracula"
-  }
-
    -9. Click Execute.

    -

    Check the Server Response section. On successful invocation, you will receive the 201 HTTP code.

    -
    9. -
-

Similarly, you can expand and try out the GET and DELETE methods.

-

Step 6: Consume the service

-

Now that the Reading List Service is deployed and available in the Choreo Marketplace, application developers can discover the service via the Marketplace and consume it.

-

In this section of the guide, you will deploy a sample front-end application to consume the service. This application will serve as the interface for users to interact with the reading list. The sample application used in this guide is designed to personalize the book lists based on the user ID that it obtains from its identity provider.

-

To host the front-end application in Choreo, you will create a web application component, set up authentication for it, and deploy it. To establish a connection between your web application and the deployed service, you will create a Connection.

-

Step 6.1: Create a web application to consume the service

-

To create a web application component, follow the steps given below:

-
    -
  1. In the Choreo Console header, click the Project list and select the project that you created in step 1.
    2. -
  2. On the project home page, click + Create under Component Listing.
    3. -
  3. Click the Web Application card.
    4. -
  4. -

    Enter a display name, unique name, and a description to create the web application. You can enter the values given below:

    -
    -

    Info

    -

    In the Component Name field, you must specify a name to uniquely identify the component in various contexts. The value is editable only at the time you create the component. You cannot change the name after you create the component.

    -
    - - - - - - - - - - - - - - - - - - - - - -
    FieldValue
    Component Display NameReading List Web App
    Component Namereading-list-web-app
    DescriptionFront-end application for the reading list service
    -
    5. -
  5. -

    Go to the GitHub tab.

    -
    6. -
  6. -

    To allow Choreo to connect to your GitHub account, click Authorize with GitHub. If you have not already connected your GitHub repository to Choreo, enter your GitHub credentials and select the repository you created in the prerequisites section to install the Choreo GitHub App.

    -

    Alternatively, you can paste the Choreo sample Book List Service repository URL in the Provide Repository URL field to connect to it without requiring authorization from the Choreo Apps GitHub application. However, authorizing the repository with the Choreo GitHub App is necessary if you want to enable Auto Deploy for the component.

    -
    -

    Note

    -

    The Choreo GitHub App requires the following permissions:

    -
      -
    • Read and write access to code and pull requests.
      • -
    • Read access to issues and metadata.
      • -
    -

    You can revoke access if you do not want Choreo to have access to your GitHub account. However, write access is exclusively utilized for sending pull requests to a user repository. Choreo will not directly push any changes to a repository.

    -
    -
    7. -
  7. -

    Enter the following information:

    - - - - - - - - - - - - - - - - - - - - - -
    FieldDescription
    OrganizationYour GitHub account
    Repositorychoreo-sample-book-list-app
    Branchmain
    -
    8. -
  8. -

    Select React as the buildpack because the sample front-end application is a React application built with Vite.

    -
    9. -
  9. -

    Enter the following information:

    - - - - - - - - - - - - - - - - - - - - - - - - - -
    FieldValue
    Project Directory/choreo-sample-book-list-app/reading-list-front-end-with-managed-auth
    Build Commandnpm install && npm run build
    Build Pathdist
    Node Version18
    -
    10. -
  10. -

    Click Create. This initializes the component with the implementation from your GitHub repository and takes you to the Overview page of the component.

    -
    11. -
-

Step 6.2: Create a connection between the web application and the deployed service

-

A connection allows you to integrate the service you intend to deploy on Choreo with other services on Choreo or external resources. For more information on Choreo Connections refer to the Connection documentation.

-

To establish a connection between the web application you created and the deployed service, follow the steps given below:

-
    -
  1. In the left navigation menu, click Dependencies and then click Connections.
    2. -
  2. Click + Create.
    3. -
  3. In the Select a Service pane, click Reading List Service.`
    4. -
  4. -

    Specify values as follows for each of the fields:

    - - - - - - - - - - - - - - - - - -
    FieldValue
    NameReading List Connection
    DescriptionConnection to the reading list
    -
    5. -
  5. -

    Click Create. This creates the connection and displays the service URL of the connection for -each environment the service is deployed in. In this guide, you will see the service URL for the Development environment. You can copy the service URL to use when you configure the web application before deploying it.

    -
    6. -
-

Step 6.3: Build the web application component

-

To build the web application, follow the steps given below:

-
    -
  1. In the left navigation menu, click Build.
    2. -
  2. In the Builds pane, click Build Latest.
    3. -
-

!!! note - Building the service component may take a while. You can track the progress via the logs in the Build Details pane. Once the build process is complete, the build status changes to Success.

-

Step 6.4: Configure and deploy the web application

-

In this step, you will configure managed authentication, create a user to access the web application, and then deploy the web application. For more information on Choreo's managed authentication capability, see the Managed Authentication documentation.

-

To configure managed authentication, follow the steps given below:

-
    -
  1. In the left navigation menu, click Deploy.
    2. -
  2. In the Set Up card, click Configure and Deploy. This opens the Configure & Deploy pane, where you can specify values for the mount file.
    3. -
  3. -

    Specify the following in the config.js file mount.

    -
      -
    • -

      You must replace <Service URL> with the value that you copied when creating a connection to the Reading List Service in step 6.2.

      -
      window.configs = {
-    apiUrl: '<Service URL>',
-};
-
      - -
      • -
    -
    -

    Tip

    -

    You can refer to the configuration file mounted at /app/public as ./public/config.js within your web application.

    -
    -
    4. -
  4. -

    Click Next. This opens the Authentication pane.

    -
    5. -
  5. -

    Under Authentication Settings, make sure that you have the Managed authentication with Choreo toggle enabled.

    -
    -

    Tip

    -

    Managed authentication is enabled by default when you create a web application using React, Angular, or Vue.js buildpacks.

    -
    -
    6. -
  6. -

    Specify values as follows for each of the fields:

    - - - - - - - - - - - - - - - - - - - - - -
    FieldValue
    Post Login Path/
    Post Logout Path/
    Error Path/
    -
    7. -
-

Next, you can create a user to access the web application.

-

To create a user to access the readingListApp application, follow the steps given below:

-
    -
  1. Under Manage Users, click + Create.
    2. -
  2. -

    To proceed with creating a user with the populated username and password, click Create. Make sure you copy the populated username and password to use when you test the front-end application.

    -
    -

    Tip

    - -
    -
    3. -
-

Now, you can deploy the web application.

-

To deploy the web application and obtain the URL to access it, follow the steps given below:

-
    -
  1. In the Authentication pane, click Deploy. The deployment may take a few minutes to complete.
    2. -
  2. Once you deploy the web application, copy the Web App URL from the development environment card.
    3. -
  3. Navigate to the web app URL. You can verify that you have successfully hosted the web application.
    4. -
-

Step 7: Test the front-end application

-

To test the front-end application and send requests to the Reading List Service via it, follow the steps given below:

-
    -
  1. Access the front-end application via its web URL that you copied in the above step.
    2. -
  2. -

    Click Login, and sign in with the credentials of the user that you created.

    -

    The application opens as follows.

    -

    Front-end application

    -
    3. -
  3. -

    Add three new reading items with different statuses.

    -

    For example, the details can be as follows:

    - - - - - - - - - - - - - - - - - - - - - - - - - -
    TitleAuthorStatus
    The Museum of InnocenceOrhan Pamukreading
    The Remains of the DayKazuo Ishiguroto_read
    David CopperfieldCharles Dickensread
    -

    To add each record, follow the steps given below:

    -
      -
    1. Click + Add New.
      2. -
    2. Enter values for the Name, Author, and Status fields.
      3. -
    3. Click Save.
      4. -
    -

    Three tabs open for each status. To delete a reading list item, you can click Delete.

    -
    4. -
-

To verify whether the reading list is personalized for each user, you can sign in as a different user. The reading list items you entered above will not appear for the other user.

-

Congratulations! You have successfully exposed a service endpoint via Choreo and securely consumed it from a web application.

-

After you have successfully tested your service and web application, you can now try out various other Choreo features such as managing, observing, DevOps, etc., similar to any other component type within Choreo.

- - - - - - -
-
- - -
- - - -
- - -
- - - -
-
-
- - - - - - - - - - - - - - - - - \ No newline at end of file diff --git a/en/site/quick-start-guides/deploy-your-first-service/index.html b/en/site/quick-start-guides/deploy-your-first-service/index.html deleted file mode 100644 index 5a26ed465..000000000 --- a/en/site/quick-start-guides/deploy-your-first-service/index.html +++ /dev/null @@ -1,3483 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - Deploy Your First Service - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- - - -
- - - - - - -
- - -
- -
- - - - - - - -
-
- - - -
-
-
- - - - -
-
-
- - - -
-
-
- - - -
-
-
- - - -
-
- - - - - - - - - - - - - - - - - - - - -

Deploy Your First Service

-

Choreo, an Internal Developer Platform (IDevP), simplifies the deployment, monitoring, and management of your cloud-native services, allowing you to focus on innovation and implementation.

-

Choreo allows you to easily deploy services you've created in your preferred programming language in just a few steps.

-

In this guide, you will:

-
    -
  • Use a pre-implemented service that has resources to maintain a book list.
    • -
  • Build and deploy the service in Choreo using the Nodejs buildpack. It runs on port 8080.
    • -
  • Test the service.
    • -
-

For a video tutorial that walks you through these steps, see Deploy Your First Service with Choreo.

-

Prerequisites

-
    -
  1. -

    You must have a GitHub account with a repository that contains your service implementation. To proceed with the steps in this guide, you can fork the Choreo sample book list service repository, which contains the sample for this guide.

    -
    2. -
  2. -

    If you are signing in to the Choreo Console for the first time, create an organization as follows:

    -
      -
    1. Go to https://console.choreo.dev/, and sign in using your Google, GitHub, or Microsoft account.
      2. -
    2. Enter a unique organization name. For example, Stark Industries.
      3. -
    3. Read and accept the privacy policy and terms of use.
      4. -
    4. Click Create.
      5. -
    -

    This creates the organization and opens the organization home page.

    -
    3. -
-

Learn the repository file structure

-

Let's familiarize ourselves with the key files in this sample application. The below table gives a brief overview of the important files in the sample book list service.

-
-

Note

-

The following file paths are relative to the path <choreo-sample-book-list-service>/.

-
- - - - - - - - - - - - - - - - - - - - - -
FilepathDescription
app.mjsThe Node.js (JavaScript) based service code.
.choreo/endpoints.yamlChoreo-specific configuration that provides information about how Choreo exposes the service.
openapi.yamlOpenAPI contract of the service. This is required to publish our service as a managed API. This openapi.yaml file is referenced by the .choreo/endpoints.yaml.
-

Let's get started!

-

Step 1: Create a project

-

Follow the steps given below to create a project:

-
    -
  1. Go to https://console.choreo.dev/ and sign in. This opens the organization home page.
    2. -
  2. On the organization home page, click + Create Project.
    3. -
  3. -

    Enter a display name, unique name, and description for the project. You can enter the values given below:

    -
    -

    Info

    -

    In the Name field, you must specify a name to uniquely identify your project in various contexts. The value is editable only at the time you create the project. You cannot change the name after you create the project.

    -
    - - - - - - - - - - - - - - - - - - - - - -
    FieldValue
    Project Display NameBook List Project
    Namebook-list-project
    Project DescriptionMy sample project
    -
    4. -
  4. -

    Click Create. This creates the project and takes you to the project home page.

    -
    5. -
-

Step 2: Create a service component

-

Let's create a service component by following these steps:

-
    -
  1. On the project home page, click Service under Create a Component.
    2. -
  2. -

    Enter a unique name and a description for the service. For this guide, let's enter the following values:

    - - - - - - - - - - - - - - - - - -
    FieldValue
    Component Display NameBook List
    DescriptionGets the book list
    -
    3. -
  3. -

    Go to the GitHub tab.

    -
    4. -
  4. -

    To allow Choreo to connect to your GitHub account, click Authorize with GitHub. If you have not already connected your GitHub repository to Choreo, enter your GitHub credentials and select the repository you created in the prerequisites section to install the Choreo GitHub App.

    -

    Alternatively, you can paste the Choreo sample Book List Service repository URL in the Provide Repository URL field to connect to it without requiring authorization from the Choreo Apps GitHub application. However, authorizing the repository with the Choreo GitHub App is necessary if you want to enable Auto Deploy for the component.

    -
    -

    Note

    -

    The Choreo GitHub App requires the following permissions:

    -
      -
    • Read and write access to code and pull requests.
      • -
    • Read access to issues and metadata.
      • -
    -

    You can revoke access if you do not want Choreo to have access to your GitHub account. However, write access is exclusively utilized for sending pull requests to a user repository. Choreo will not directly push any changes to a repository.

    -
    -
    5. -
  5. -

    Enter the following information:

    - - - - - - - - - - - - - - - - - - - - - -
    FieldDescription
    OrganizationYour GitHub account
    Repositorychoreo-sample-book-list-service
    Branchmain
    -
    6. -
  6. -

    Select the NodeJS buildpack.

    -
    7. -
  7. -

    Enter the following information.

    - - - - - - - - - - - - - - - - - -
    FieldDescription
    NodeJS Project Directory/
    Language Version20.x.x
    -
    8. -
  8. -

    Click Create.

    -
    9. -
-

You have successfully created a Service component with the NodeJS buildpack. Now let's build and deploy the service.

-

Step 3: Build and deploy

-

Now that the source repository is connected and Choreo has set up the endpoints based on the repository's configuration, it's time to proceed with building the service. Choreo will create a Docker image in the build process. You can then deploy the built Docker image and test the book list service.

-

Step 3.1: Build

-

To build the service, follow these steps:

-
    -
  1. On the project home page, click the Book List component listed under Component Listing. This takes you to the component overview page.
    2. -
  2. In the left navigation, click Build.
    3. -
  3. Click Build Latest.
    4. -
-

!!! note - Building the service component may take a while. You can track the progress via the logs in the Build Details pane. Once the build process is complete, the build status changes to Success.

-

Step 3.2: Deploy

-

Now you are ready to deploy the service. Follow these steps:

-
    -
  1. In the left navigation menu, click Deploy.
    2. -
  2. On the Set Up card, click Configure & Deploy.
    3. -
  3. In the Environment Configurations pane, click Next.
    4. -
  4. In the File Mount pane, click Next.
    5. -
  5. -

    Review the Endpoint Details and click Deploy.

    -
    -

    Note

    -

    Deploying the service component may take a while. You can track the progress by observing the logs. Once the deployment is complete, the build status changes to Active on the Development environment card.

    -
    -
    6. -
-

Step 4: Test the service

-

To test the Book List service via the integrated OpenAPI Console in Choreo, follow the steps given below:

-
    -
  1. In the Choreo Console left navigation menu, click Test and then click Console.
    2. -
  2. In the OpenAPI Console that opens, select Development from the environment drop-down list.
    3. -
  3. In the Endpoint list, select Books REST Endpoint.
    4. -
  4. Expand the GET /books method and click Try it out.
    5. -
  5. Click Execute.
    6. -
  6. Check the Server Response section.
    7. -
-

Similarly, you can expand and try out the other methods.

-

After you have successfully tested your service, you can now try out various other Choreo features such as managing, observing, DevOps, etc., similar to any other component type within Choreo.

- - - - - - -
-
- - -
- - - -
- - -
- - - -
-
-
- - - - - - - - - - - - - - - - - \ No newline at end of file diff --git a/en/site/quick-start-guides/deploy-your-first-static-web-application/index.html b/en/site/quick-start-guides/deploy-your-first-static-web-application/index.html deleted file mode 100644 index 4518c7a61..000000000 --- a/en/site/quick-start-guides/deploy-your-first-static-web-application/index.html +++ /dev/null @@ -1,3354 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - Deploy Your First Static Web Application - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- - - -
- - - - - - -
- - -
- -
- - - - - - - -
-
- - - -
-
-
- - - - -
-
-
- - - -
-
-
- - - -
-
-
- - - -
-
- - - - - - - - - - - - - - - - - - - - -

Deploy Your First Static Web Application

-

Choreo is an internal developer platform as a service that takes care of the complexities of building platforms, allowing application developers to focus on innovation and implementation. Choreo streamlines the entire process of building, deploying, monitoring, and managing your cloud-native applications.

-

In this quick start guide, you will explore how easy it is to deploy a web application using Choreo. Here, you will use a simple web application designed to add tasks to a to-do list.

-

This guide walks you through the following steps:

-
    -
  • Create a project.
    • -
  • Create a Web Application component and connect it to the GitHub repository that includes the web application implementation.
    • -
  • Build the web application.
    • -
  • Deploy the web application and access it.
    • -
-

For a video tutorial that walks you through these steps, see Deploy a Static Web App on Choreo.

-

Prerequisites

-

Before you try out this guide, complete the following:

-
    -
  1. Fork the choreo-sample-todo-list-app - repository, which contains the sample for this guide.
    2. -
  2. -

    If you are signing in to the Choreo Console for the first time, create an organization as follows:

    -
      -
    1. Go to https://console.choreo.dev/, and sign in using your Google, GitHub, or Microsoft account.
      2. -
    2. Enter a unique organization name. For example, Stark Industries.
      3. -
    3. Read and accept the privacy policy and terms of use.
      4. -
    4. Click Create.
      5. -
    -

    This creates the organization and opens the organization home page.

    -
    3. -
-

Step 1: Create a project

-

Follow the steps given below to create a project:

-
    -
  1. Go to https://console.choreo.dev/ and sign in. This opens the organization home page.
    2. -
  2. On the organization home page, click + Create Project.
    3. -
  3. -

    Enter a display name, unique name, and description for the project. You can enter the values given below:

    -
    -

    Tip

    -

    In the Name field, you must specify a name to uniquely identify your project in various contexts. The value is editable only at the time you create the project. You cannot change the name after you create the project.

    -
    - - - - - - - - - - - - - - - - - - - - - -
    FieldValue
    Project Display NameSample project
    Namesample-project
    Project DescriptionMy sample project
    -
    4. -
  4. -

    Click Create. This creates the project and opens the project home page.

    -
    5. -
-

Step 2: Create a Web Application component

-

To create a Web Application component, follow the steps given below:

-
    -
  1. On the project home page, click Web Application under Create a Component.
    2. -
  2. Enter a unique name and a description for the web application.
    3. -
  3. Go to the GitHub tab.
    4. -
  4. -

    To allow Choreo to connect to your GitHub account, click Authorize with GitHub. If you have not already connected your GitHub repository to Choreo, enter your GitHub credentials and select the repository you created in the prerequisites section to install the Choreo GitHub App.

    -

    Alternatively, you can paste the choreo-sample-todo-list-app repository URL in the Provide Repository URL field to connect to it without requiring authorization from the Choreo Apps GitHub application. However, authorizing the repository with the Choreo GitHub App is necessary if you want to enable Auto Deploy for the component.

    -
    -

    Note

    -

    The Choreo GitHub App requires the following permissions:

    -
      -
    • Read and write access to code and pull requests.
      • -
    • Read access to issues and metadata.
      • -
    -

    You can revoke access if you do not want Choreo to have access to your GitHub account. However, write access is exclusively utilized for sending pull requests to a user repository. Choreo will not directly push any changes to a repository.

    -
    -
    5. -
  5. -

    Enter the following information:

    - - - - - - - - - - - - - - - - - - - - - -
    FieldValue
    OrganizationYour GitHub account
    Repositorychoreo-sample-todo-list-app
    Branchmain
    -
    6. -
  6. -

    Select NodeJS as the Buildpack

    -
    7. -
  7. -

    Enter the following information:

    - - - - - - - - - - - - - - - - - - - - - -
    FieldValue
    NodeJS Project Directory/
    Language Version20.x.x
    Port8080
    -
    8. -
  8. -

    Click Create. Choreo initializes the component with the sample implementation and opens the Overview page of the component.

    -
    9. -
-

Now let's build and deploy the web application.

-

Step 3: Build your web application

-

To build the web application, follow the steps given below:

-
    -
  1. In the left navigation menu, click Build.
    2. -
  2. -

    In the Builds pane, click Build Latest.

    -
    -

    Note

    -

    Building the component may take a while. You can track the progress via the logs in the Build Details pane. Once the build process is complete, the build status changes to Success.

    -
    -
    3. -
-

Now you can proceed to deploy your web application.

-

Step 4: Deploy and access your web application

-
    -
  1. In the left navigation menu, click Deploy.
    2. -
  2. In the Set Up card, click Configure and Deploy. This opens the Configure & Deploy pane, where you can add a file mount if necessary. In this guide you will not add a file mount.
    3. -
  3. Click Deploy. The deployment to the Development environment may take a few minutes to complete. On successful deployment, you will see the Deployment Status as Active in the Development card.
    4. -
  4. To verify that you have successfully hosted the web application, click the Web App URL on the Development card. This takes you to the web application. You can try creating one or more new tasks by specifying an appropriate task ID and task label.
    5. -
-

After you have successfully tested your web application, you can now try out various other Choreo features such as observability, DevOps, etc., similar to any other component type within Choreo.

- - - - - - -
-
- - -
- - - -
- - -
- - - -
-
-
- - - - - - - - - - - - - - - - - \ No newline at end of file diff --git a/en/site/quick-start-guides/expose-a-service-as-a-managed-api-with-choreo-api-manager/index.html b/en/site/quick-start-guides/expose-a-service-as-a-managed-api-with-choreo-api-manager/index.html deleted file mode 100644 index 91cc4aadf..000000000 --- a/en/site/quick-start-guides/expose-a-service-as-a-managed-api-with-choreo-api-manager/index.html +++ /dev/null @@ -1,15 +0,0 @@ - - - - - - Redirecting... - - - - - - -Redirecting... - - diff --git a/en/site/reference/connect-with-protected-third-party-applications/index.html b/en/site/reference/connect-with-protected-third-party-applications/index.html deleted file mode 100644 index 618e92ae7..000000000 --- a/en/site/reference/connect-with-protected-third-party-applications/index.html +++ /dev/null @@ -1,15 +0,0 @@ - - - - - - Redirecting... - - - - - - -Redirecting... - - diff --git a/en/site/references/alerting/index.html b/en/site/references/alerting/index.html deleted file mode 100644 index b0b2e108a..000000000 --- a/en/site/references/alerting/index.html +++ /dev/null @@ -1,15 +0,0 @@ - - - - - - Redirecting... - - - - - - -Redirecting... - - diff --git a/en/site/references/choreo-limitations/index.html b/en/site/references/choreo-limitations/index.html deleted file mode 100644 index 64edd7d6d..000000000 --- a/en/site/references/choreo-limitations/index.html +++ /dev/null @@ -1,3219 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - Choreo Limitations - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- - - -
- - - - - - -
- - -
- -
- - - - - - - -
-
- - - -
-
-
- - - - -
-
-
- - - -
-
-
- - - -
-
-
- - - -
-
- - - - - - - - - - - - - - - - - - - - -

Choreo Limitations

-

Explore key limitations in Choreo, covering areas like HTTP request parameters, components, applications, and API definition files. You can gain insights into the limitations to enhance your understanding and optimize your use of Choreo effectively.

-

API management limits

-

Below are key limitations when working with APIs in Choreo:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
ResourceLimit
Maximum request payload10 MB
URL size2 KB
Request header
  • Request Headers total: 40 KB
  • Max Single Request header: 10 KB
Total request duration
  • Minimum: 10 seconds
  • Default: 1 minute
  • Maximum: 5 minutes
Size for API Definition (OpenAPI document)10 Mb
Number of APIs for PDP1000 API deployments
Number of APIs per organization (free tier)5 APIs for free users
Number of Developer Portal applications per organization (free tier)10 applications for free users
-

Choreo Cloud Data Plane limits

-

Below are key limitations when working with web applications in the Choreo cloud data plane:

- - - - - - - - - - - - - - - - - - - - - -
ResourceLimit
Request size limit (including headers, cookies, and payloads)256 KB
Response body size limit20 MB
Number of open ports permitted per web application1
While it is possible to have multiple ports open for project-level communication within a data plane, incoming internet traffic can only be directed to a single port. This contrasts with Service-type components, which allow for multiple endpoints.
- - - - - - -
-
- - -
- - - -
- - -
- - - -
-
-
- - - - - - - - - - - - - - - - - \ No newline at end of file diff --git a/en/site/references/connect-with-protected-third-party-applications/index.html b/en/site/references/connect-with-protected-third-party-applications/index.html deleted file mode 100644 index a296aff39..000000000 --- a/en/site/references/connect-with-protected-third-party-applications/index.html +++ /dev/null @@ -1,15 +0,0 @@ - - - - - - Redirecting... - - - - - - -Redirecting... - - diff --git a/en/site/references/define-configurable-variables/index.html b/en/site/references/define-configurable-variables/index.html deleted file mode 100644 index 181da5513..000000000 --- a/en/site/references/define-configurable-variables/index.html +++ /dev/null @@ -1,15 +0,0 @@ - - - - - - Redirecting... - - - - - - -Redirecting... - - diff --git a/en/site/references/faq/index.html b/en/site/references/faq/index.html deleted file mode 100644 index 28ca90870..000000000 --- a/en/site/references/faq/index.html +++ /dev/null @@ -1,4482 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - FAQ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- - - -
- - - - - - -
- - -
- -
- - - - - - - -
-
- - - -
-
-
- - - - -
-
-
- - - -
-
-
- - - -
-
-
- - - -
-
- - - - - - - - - - - - - - - - - - - - -

Frequently Asked Questions

-

General

-

Q: What is Choreo?

-

Choreo is an internal developer platform designed to accelerate the creation of digital experiences. With Choreo, you can effortlessly build, deploy, monitor, and manage your cloud native applications. Our goal is to enhance developer productivity and enable innovation.

-

Q: What is an organization in Choreo?

-

An organization is a logical grouping of users and their resources. It may represent a company, community, or a single user. Users can belong to multiple organizations, and each organization can have different roles assigned to its users to control access to Choreo features.

-

Q: What is a project in Choreo?

-

A project is a logical grouping of related components to help you organize your work. Each project provides runtime isolation through namespaces when you deploy components.

-

Q: What is a component in Choreo?

-

A component is a workload designed to run on Choreo. Examples of components include integrations, APIs, microservices, manual/scheduled jobs, web apps, and triggers.

-

Q: What is the difference between an internal and external API?

-

In Choreo, you can publish an API as an internal or an external API. A user or an application can access an external API publicly over the internet, whereas an internal API is only accessible through other components within the same organization.

-

Q: What is a connector in Choreo Marketplace?

-

A connector is a reusable Ballerina package that simplifies connecting to external or internal systems and APIs, such as Salesforce, SAP, GitHub, and Twilio. You can use the connectors available in the Choreo marketplace to implement your integration use cases. Connectors can be created and published by both WSO2 and Choreo users.

-

Q: What is a trigger in Choreo Marketplace?

-

A trigger is a construct that enables users to receive known event payloads from external systems, facilitating event-driven programming.

-

Q: What is a sample/template in Choreo?

-

A sample or template is a prebuilt Ballerina program that covers a popular integration use case or pattern. Examples include connecting Salesforce to Slack or implementing content-based routing.

-

Q: What are the support options in Choreo?

-

You can find information about our support plans, including free, basic, and enterprise options at https://wso2.com/choreo/customer-support/.

-

Q: How can I perform log monitoring or analytics for the Azure environment?

-

If you have a log monitoring product or service, such as Azure Monitor, you can use it together with Choreo. Note: The log monitoring tool is not included in the infrastructure cost.

-

Q: What is the maximum request payload size supported by Choreo?

-

Choreo allows a maximum request payload size of 10 MB.

-

Q: What source control software does Choreo support?

-

Choreo now supports GitHub, Bitbucket and GitLab.

-

Q: Why don't I see the undeployed builds for my component in Choreo?

-

You are allowed to build your component any number of times. However, Choreo has a limit on retaining undeployed builds. For users on the free-tier, Choreo will retain only one undeployed build. For those on any other tier, Choreo will retain the latest five undeployed builds.

-

Q: What is Ballerina?

-

Ballerina is an open-source programming language designed for the cloud. It simplifies the process of using, combining, and creating network services. When you use Ballerina to write integrations in Choreo, you can save time and deliver 2-3x faster. To learn more, check out https://ballerina.io/.

-

Q: What is Asgardeo?

-

Asgardeo is an identity provider (IdP) that allows developers to secure access for consumers, business partners, employees, and APIs. Asgardeo is Choreo’s default IDP. To learn more, visit https://wso2.com/asgardeo/.

-

Q: Why don’t I see the region selector on the project creation page?

-

If you are a Choreo cloud data plane user, you can create projects in multiple regions only if you have a paid subscription in Choreo. Otherwise, your projects will be created in the same region you selected when onboarding the organization.

-

If you are a private data plane user, there will be no region selector in project creation at all.

-

Q: As a Cloud Data Plane user, how can I create components in multiple data planes?

-

When an organization admin onboards a new organization in Choreo, they can choose the preferred data plane. Choreo then sets the selected data plane as the default for the entire organization. Subsequently, users within the free tier of the cloud data plane can create components only in the set default data plane. If a free-tier user needs to create components in a different data plane, the user must get a paid subscription.

-

Security and data protection

-

Q: How is data managed in Choreo?

-

Choreo manages data using WSO2 containers and Kubernetes clusters, which provide scalability, resilience, and security. Find out more here.

-

Q: What is the WSO2 Subprocessor list?

-

This is a detailed list of all subprocessors used by WSO2, including their name, location, and purpose. This information is updated frequently to ensure compliance with data protection regulations and is found here.

-

Q: How do we secure WSO2 Private and Public Clouds?

-

WSO2 uses a range of security controls and design patterns to protect against several threats, including internal attacks, software supply chain attacks, service and platform attacks, and more. Find out more regarding this here.

-

Q: How can I connect a Choreo component with a protected third-party application?

-

To connect a Choreo component with a third-party application, it is necessary to establish seamless communication between the component and the protected third-party application, especially when connecting to external databases like MySQL, MSSQL, PGSQL, Oracle DB, etc. -To ensure this, the requests coming from the Choreo data plane must be allowed by adding the specific data plane IP ranges to your allowlist.

-
    -
  • -

    If your component is deployed in the Choreo US data plane, add the following IP range to your allowlist:

    -
      -
    • 20.22.170.144/28
      • -
    -
    • -
  • -

    If your component is deployed in the Choreo EU data plane, add the following IP range to your allowlist:

    -
      -
    • 20.166.183.112/28
      • -
    -
    • -
  • -

    If you are working on the Cybertruck Challenge, add the following IP range to your allowlist:

    -
      -
    • 20.190.30.48/28
      • -
    -
    • -
-

Data planes

-

Q: What is a Choreo control plane?

-

The Choreo control plane is a centralized management component that oversees and coordinates the workloads deployed by customers. It provides a unified point of control and visibility for the organization, allowing administrators to manage, monitor, and orchestrate the organization’s resources efficiently.

-

Q: What is a data plane?

-

A data plane in Choreo is a computing environment designed for running customer workloads. These environments are hosted in either a dedicated cloud infrastructure owned by the customer (private data planes) or on public cloud infrastructure owned by WSO2, also known as the Choreo data plane.

-

Q: Which regions support the Choreo data plane(CDP)?

-

The Choreo data plane is currently supported in the US East 2 and North Europe. However, WSO2 is planning to add support for additional regions as needed.

-

Q: Which regions support private data planes(PDPs)?

-

Private data planes can be deployed in any region where Azure and AWS are available and meet the requirements for PDPs.

-

Q: If I want to use my Azure AKS instances as the private data plane, what are the minimum requirements I should meet?

-

We recommend using a minimum of two (2) workload nodes to ensure high availability.

-

Q: Are the Choreo control plane and data planes highly available? Are they running on multiple clusters?

-

The Choreo control plane and data plane are designed for high availability using Azure components like AKS, MSSQL, ACR, KV, Service Bus, and so on, with a high availability of 99.99%, which allows at least three workload nodes. In the event of a node failure or upgrade, this setup provides reliable failover. WSO2 also has a backup and recovery strategy in place, including continuous restore drills. If you require AKS cluster-level redundancy, we can consider multiple zones. In this case, the cost will include an additional infrastructure cost.

-

Environments

-

Q: As a Choreo cloud data plane user, why can't I create environments?

-

You can create environments only if you have a paid subscription in Choreo. It can be either Pay-as-you-Go (PAYG) or an Enterprise plan.

-

Q: I am a Pay-As-You-Go (PAYG) customer using the Choreo cloud data plane. How many environments can I create?

-

You can create up to 5 environments at the organization level, including the existing Development & Production environments by default. If you have projects in both data planes (US & EU), there will be 4 environments already created in total, and you will only be allowed to create one additional environment either in the US or EU data plane.

-

Q: I am an Enterprise subscription customer using the Choreo private data plane. How many environments do I get?

-

As an Enterprise subscription customer, the number of environments you can use is not limited. However, the more environments you use, the more resources you will consume in the data plane for the workload you deploy. This may result in higher infrastructure costs for the private data plane.

-

Q: As a Choreo cloud data plane user, why don’t I see both US & EU data planes in the data plane selector when creating an environment?

-

You will see both US & EU data planes only if you have a paid subscription and have created projects in both US & EU data planes.

-

Q: I am a customer who use Choreo in a private data plane. How many environments can I create?

-

Initially, you will receive the requested number of environments when establishing your private data plane. Subsequently, you can create additional environments as needed.

-

Billing and support

-

Q: Whom do I reach out to if I have a billing question?

-

You can reach out to cloud-billing-support@wso2.com or create a support ticket via our support portal.

-

Q: What's a Developer plan?

-

A Developer plan allows you to try out Choreo’s capabilities at no cost. It’s ideal for proof of concept (PoC) tasks or workloads with limited transactions. This plan allows you to experiment with up to 5 components and provides US$1,000/year of Choreo data plane (CDP) credits.

-

Q: How do I calculate the infrastructure costs?

-

Calculating infrastructure costs depends on the type of workload you want to manage. Here are a few examples:

-
    -
  • Example 1: Managing existing APIs as an API proxy with simple mediation; no additional infrastructure costs.
    • -
  • Example 2: Managing existing APIs as an API proxy with complex mediation and policies; Choreo will deploy 1 x container to handle these mediation and policies at approximately US$57.25 per month per API.
    • -
  • Example 3: Creating, deploying, and managing a new API or integration within Choreo; pay for 1 x component + infrastructure cost. Each container deployed will be approximately US$57.25 per month on the default configuration provided by Choreo. Additional resources will be charged based on the type of resource required.
    • -
  • Example 4: Creating, deploying, and managing a microservice; the same approach as example 3.
    • -
-

Q: What are the component limitations?

-
    -
  • Developer plan: Allows up to a maximum of five free components and unlimited paid components.
    • -
  • PAYG plan: Allows unlimited paid components.
    • -
  • Enterprise plan: Allows unlimited paid components.
    • -
-

Q: How do I read the bill?

-

Your bill will detail the number of components used, infrastructure consumed, support plans used, and any additional services you may have purchased. If you are unsure about any charges on your bill, reach out to choreo-support@wso2.com for clarification.

-

Q: Is support included in the Choreo Enterprise plan?

-

The Choreo Enterprise plan does not automatically include support; however, you can purchase support plans in addition to the Enterprise plan at any time. Find out more at https://wso2.com/choreo/customer-support/.

-

Q: I am an Enterprise subscription customer who wants to use the Choreo private data plane. What costs will I incur in addition to the subscription and support plan?

-

You can start by using a basic plan or contact us for an Enterprise support plan.

-

Q: I want to upgrade from PAYG to an Enterprise subscription. Will there be an outage during the upgrade?

-

No, there are no outages when upgrading a plan.

-

Choreo CLI

-

Q: How do I uninstall the CLI?

-

If you didn't download the binary directly, you can uninstall the CLI by deleting the .choreo directory in the -home directory of your operating system.

-

Q: How do I update the CLI?

-

You can update the CLI by running the following command: -

curl -o- https://cli.choreo.dev/install.sh | bash
-

-

Q: What are the supported component types in the CLI?

-

The Choreo CLI currently supports the following component types: -- Service -- Web Application -- Webhook -- Scheduled Task -- Manual Task

-

Q: How do I get help with a specific command in the CLI?

-

You can get help with a specific command by running the following command: -

choreo <command> --help
-

-

Q: What are the build configurations required when creating components using the CLI?

-

You can configure the component build configurations depending on the component type as follows:

-
choreo create component <name> --project <name> --build-configs='key1=value1,key2=value2'
-choreo create component <name> --project <name> --build-configs='key1=value1' --build-configs='key2=value2'
-
- -

The build configurations required for existing buildpacks are as follows:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Component TypeBuildpackRequired Configurations
ServicePython -
    -
  • buildPackLangVersion: Language Version
    • -
-
Node.js -
    -
  • buildPackLangVersion: Language Version
    • -
-
Java -
    -
  • buildPackLangVersion: Language Version
    • -
-
Go -
    -
  • buildPackLangVersion: Language Version
    • -
-
PHP -
    -
  • buildPackLangVersion: Language Version
    • -
-
Ruby -
    -
  • buildPackLangVersion: Language Version
    • -
-
Docker -
    -
  • dockerFilePath: Path to the docker file
    • -
-
Ballerina -
    -
  • Not Applicable
    • -
      -
WSO2 MI -
    -
  • Not Applicable
    • -
      -
.Net -
    -
  • buildPackLangVersion: Language Version
    • -
      -
WebappPython -
    -
  • buildPackLangVersion: Language Version
    • -
  • port: Port
    • -
-
Node.js -
    -
  • buildPackLangVersion: Language Version
    • -
  • port: Port
    • -
-
Go -
    -
  • buildPackLangVersion: Language Version
    • -
  • port: Port
    • -
-
PHP -
    -
  • buildPackLangVersion: Language Version
    • -
  • port: Port
    • -
-
Ruby -
    -
  • buildPackLangVersion: Language Version
    • -
  • port: Port
    • -
-
.Net -
    -
  • buildPackLangVersion: Language Version
    • -
  • port: Port
    • -
-
Docker -
    -
  • dockerFilePath: Path to the docker file
    • -
  • port: Port
    • -
-
Static website -
    -
  • Not Applicable
    • -
      -
React -
    -
  • buildCommand: Command to be used for building the component
    • -
  • outputDirectory: Output directory for the component build artifacts
    • -
  • nodeVersion: Node.js version used
    • -
-
Angular -
    -
  • buildCommand: Command to be used for building the component
    • -
  • outputDirectory: Output directory for the component build artifacts
    • -
  • nodeVersion: Node.js version used
    • -
-
Vue -
    -
  • buildCommand: Command to be used for building the component
    • -
  • outputDirectory: Output directory for the component build artifacts
    • -
  • nodeVersion: Node.js version used
    • -
-
WebhookPython -
    -
  • buildPackLangVersion: Language Version
    • -
-
Node.js -
    -
  • buildPackLangVersion: Language Version
    • -
-
Java -
    -
  • buildPackLangVersion: Language Version
    • -
-
Go -
    -
  • buildPackLangVersion: Language Version
    • -
-
PHP -
    -
  • buildPackLangVersion: Language Version
    • -
-
Ruby -
    -
  • buildPackLangVersion: Language Version
    • -
-
Docker -
    -
  • dockerFilePath: Path to the docker file
    • -
-
Ballerina -
    -
  • Not Applicable
    • -
      -
WSO2 MI -
    -
  • Not Applicable
    • -
      -
Scheduled TaskPython -
    -
  • buildPackLangVersion: Language Version
    • -
-
Node.js -
    -
  • buildPackLangVersion: Language Version
    • -
-
Java -
    -
  • buildPackLangVersion: Language Version
    • -
-
Go -
    -
  • buildPackLangVersion: Language Version
    • -
-
.Net -
    -
  • buildPackLangVersion: Language Version
    • -
-
PHP -
    -
  • buildPackLangVersion: Language Version
    • -
-
Ruby -
    -
  • buildPackLangVersion: Language Version
    • -
-
Docker -
    -
  • dockerFilePath: Path to the docker file
    • -
-
Ballerina -
    -
  • Not Applicable
    • -
      -
WSO2 MI -
    -
  • Not Applicable
    • -
      -
Manual TaskPython -
    -
  • buildPackLangVersion: Language Version
    • -
-
Node.JS -
    -
  • buildPackLangVersion: Language Version
    • -
-
Java -
    -
  • buildPackLangVersion: Language Version
    • -
-
Go -
    -
  • buildPackLangVersion: Language Version
    • -
-
.Net -
    -
  • buildPackLangVersion: Language Version
    • -
-
PHP -
    -
  • buildPackLangVersion: Language Version
    • -
-
Ruby -
    -
  • buildPackLangVersion: Language Version
    • -
-
Docker -
    -
  • dockerFilePath: Path to the docker file
    • -
-
Ballerina -
    -
  • Not Applicable
    • -
      -
WSO2 MI -
    -
  • Not Applicable
    • -
      -
- - - - - - - - -
-
- - -
- - - -
- - -
- - - -
-
-
- - - - - - - - - - - - - - - - - \ No newline at end of file diff --git a/en/site/references/handle-non-ballerina-files-in-choreo/index.html b/en/site/references/handle-non-ballerina-files-in-choreo/index.html deleted file mode 100644 index e0f627126..000000000 --- a/en/site/references/handle-non-ballerina-files-in-choreo/index.html +++ /dev/null @@ -1,15 +0,0 @@ - - - - - - Redirecting... - - - - - - -Redirecting... - - diff --git a/en/site/references/manage-connectors/index.html b/en/site/references/manage-connectors/index.html deleted file mode 100644 index 30c9cc46b..000000000 --- a/en/site/references/manage-connectors/index.html +++ /dev/null @@ -1,15 +0,0 @@ - - - - - - Redirecting... - - - - - - -Redirecting... - - diff --git a/en/site/references/performance-analysis/index.html b/en/site/references/performance-analysis/index.html deleted file mode 100644 index 134164328..000000000 --- a/en/site/references/performance-analysis/index.html +++ /dev/null @@ -1,15 +0,0 @@ - - - - - - Redirecting... - - - - - - -Redirecting... - - diff --git a/en/site/references/private-data-plane-management-models/index.html b/en/site/references/private-data-plane-management-models/index.html deleted file mode 100644 index a5c971826..000000000 --- a/en/site/references/private-data-plane-management-models/index.html +++ /dev/null @@ -1,3637 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - Private Data Plane Management Models - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- - - -
- - - - - - -
- - -
- -
- - - - - - - -
-
- - - -
-
-
- - - - -
-
-
- - - -
-
-
- - - -
-
-
- - - -
-
- - - - - - - - - - - - - - - - - - - - -

Private Data Plane Management Models

-

Choreo supports various management models for private data planes (PDPs), fostering collaboration between WSO2 and customers across diverse scenarios. The following sections provide insights into WSO2's fully managed solutions and shared responsibility models, allowing you to make informed decisions regarding cloud-based operations and security.

-

WSO2 fully managed (infrastructure and PDP in WSO2 subscription) model

-

WSO2 fully managed private data planes are supported only on Azure, AWS, and GCP cloud providers.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
TaskTask descriptionResponsible partyAccountableConsultedInformed
Subscription prerequisites- Create subscriptions
- - Check quota and service limits
- - Run the Choreo compatibility prerequisite script		WSO2WSO2Customer (If required)Customer (If required)
Remote access for installationProvide owner accessWSO2WSO2WSO2WSO2
Network management- Obtain customers backend CIDR in case of VPN/peering
- - Check end-to-end connectivity (primary and failover)		WSO2/CustomerWSO2/CustomerCustomerCustomer
Firewall rules/access controlSet up firewall and required rules depending on the security tierWSO2WSO2CustomerCustomer
Infrastructure provisioning- Provision Bastion
- - Provision Kubernetes clusters		WSO2WSO2-Customer(If required)
Kubernetes cluster management- Manage Kubernetes versions
- - Increase node pool size		WSO2WSO2CustomerCustomer
Infrastructure monitoringSet up alertsWSO2WSO2-Customer(If required)
DNS management for Choreo system- Manage DNS infrastructure
- - Manage SSL certificates for Choreo system components		WSO2/CustomerWSO2/CustomerCustomerCustomer
Choreo system components deploymentSet up PDP agents via HelmWSO2WSO2--
Choreo system components managementUpgrade/patch/debug versionsWSO2WSO2-Customer(If required)
Choreo system components monitoring- Set up continuous monitoring 24x7
- - Provide monthly uptime reports		WSO2WSO2-Customer
Choreo system security monitoringIf basic tier
- - CSPM
- - Apply security patches
- - Manage supply chain security (Image scanning, SAST)
- - Manage security incidents
- If standard tier/premium tier
- - CSPM
- - Apply security patches
- - Manage supply chain security
- - Monitor runtime security alerts (Azure Defender)
- - Monitor security incident and event management (SIEM) alerts
- - Manage security incidents
- - Adhere to compliance standards		WSO2/CustomerWSO2/CustomerWSO2/CustomerWSO2/Customer
Choreo application creation/deploymentCustomerCustomerCustomerCustomer
Choreo application managementCustomerCustomerCustomerCustomer
Choreo application monitoringCustomerCustomerCustomerCustomer
Choreo application logsCustomerCustomerCustomerCustomer
- -

WSO2 fully managed (infrastructure and PDP in customer subscription) model

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
TaskTask descriptionResponsible partyAccountableConsultedInformed
Subscription prerequisites- Create subscriptions
- - Check quota and service limits
- - Run the Choreo compatibility prerequisite script		CustomerCustomerWSO2-
Remote access for installationProvide accessCustomerCustomerWSO2WSO2
Network management- Obtain customers backend CIDR in case of VPN/peering
- - Check end-to-end connectivity (primary and failover)		WSO2/CustomerWSO2/CustomerCustomerCustomer
Firewall rules/access controlSet up firewall and required rules depending on the security tierWSO2/CustomerWSO2/CustomerCustomerCustomer
Infrastructure provisioning- Provision Bastion
- - Provision Kubernetes clusters		WSO2WSO2CustomerCustomer
Kubernetes cluster management- Manage Kubernetes versions
- - Increase node pool size		WSO2WSO2CustomerCustomer
Infrastructure monitoringSet up alertsWSO2WSO2-Customer(If required)
DNS management for Choreo system- Manage DNS infrastructure
- - Manage SSL certificates for Choreo system components		WSO2/CustomerWSO2/CustomerCustomerCustomer
Choreo system components deploymentSet up PDP agents via HelmWSO2WSO2Customer-
Choreo system components managementUpgrade/patch/debug versionsWSO2WSO2-Customer(If required)
Choreo system components monitoring- Set up continuous monitoring 24x7
- - Provide monthly uptime reports		WSO2WSO2-Customer
Choreo system security monitoringIf basic tier
- - CSPM
- - Apply security patches
- - Manage supply chain security (Image scanning, SAST)
- - Manage security incidents
- If standard tier/premium tier
- - CSPM
- - Apply security patches
- - Manage supply chain security
- - Monitor runtime security alerts (Azure Defender)
- - Monitor security incident and event management (SIEM) alerts
- - Manage security incidents
- - Adhere to compliance standards		WSO2/CustomerWSO2/CustomerWSO2/CustomerWSO2/Customer
Choreo application creation/deploymentCustomerCustomerCustomerCustomer
Choreo application managementCustomerCustomerCustomerCustomer
Choreo application monitoringCustomerCustomerCustomerCustomer
Choreo application logsCustomerCustomerCustomerCustomer
- -

Customer self-managed (WSO2 provides installation script and updates) model

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
TaskTask descriptionResponsible partyAccountableConsultedInformed
Subscription prerequisites- Create subscriptions
- - Check quota and service limits
- - Run the Choreo compatibility prerequisite script		CustomerCustomerWSO2WSO2
Remote access for installationProvide owner accessCustomerCustomerWSO2-
Network management- Obtain customers backend CIDR in case of VPN/peering
- - Check end-to-end connectivity (primary and failover)		CustomerCustomerWSO2WSO2
Firewall rules/access controlSet up firewall and required rules depending on the security tierCustomerCustomerWSO2WSO2
Infrastructure provisioning- Provision Bastion
- - Provision Kubernetes clusters		CustomerCustomerWSO2WSO2(If required)
Kubernetes cluster management- Manage Kubernetes versions
- - Increase node pool size		CustomerCustomerWSO2WSO2(If required)
Infrastructure monitoringSet up alertsCustomerCustomerWSO2-
DNS management for Choreo system- Manage DNS infrastructure
- - Manage SSL certificates for Choreo system components		CustomerCustomerWSO2-
Choreo system components deploymentSet up PDP agents via HelmCustomerCustomerWSO2-
Choreo system components managementUpgrade/patch/debug versionsCustomerCustomerWSO2-
Choreo system components monitoring- Set up continuous monitoring 24x7
- - Provide monthly uptime reports		CustomerCustomerWSO2-
Choreo system security monitoringIf basic tier
- - CSPM
- - Apply security patches
- - Manage supply chain security (Image scanning, SAST)
- - Manage security incidents
- If standard tier/premium tier
- - CSPM
- - Apply security patches
- - Manage supply chain security
- - Monitor runtime security alerts (Azure Defender)
- - Monitor security incident and event management (SIEM) alerts
- - Manage security incidents
- - Adhere to compliance standards		WSO2/CustomerWSO2/CustomerWSO2/CustomerWSO2/Customer
Choreo application creation/deploymentCustomerCustomerCustomerCustomer
Choreo application managementCustomerCustomerCustomerCustomer
Choreo application monitoringCustomerCustomerCustomerCustomer
Choreo application logsCustomerCustomerCustomerCustomer
- - - - - - -
-
- - -
- - - -
- - -
- - - -
-
-
- - - - - - - - - - - - - - - - - \ No newline at end of file diff --git a/en/site/references/private-data-plane-security-levels/index.html b/en/site/references/private-data-plane-security-levels/index.html deleted file mode 100644 index 854ad663b..000000000 --- a/en/site/references/private-data-plane-security-levels/index.html +++ /dev/null @@ -1,3175 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - Private Data Plane Security Levels - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- - - -
- - - - - - -
- - -
- -
- - - - - - - -
-
- - - -
-
-
- - - - -
-
-
- - - -
-
-
- - - -
-
-
- - - -
-
- - - - - - - - - - - - - - - - - - - - -

Private Data Plane Security Levels

-

The following table outlines the private data plane security levels supported in Choreo:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Basic tierStandard tierPremium tier
Distributed denial-of-service (DDoS) protection basic *Distributed denial-of-service (DDoS) protection basic *Distributed denial-of-service (DDoS) protection premium *
Controlled admin access *Controlled admin access *Controlled admin access *
End-to-end data encryption in transitEnd-to-end data encryption in transitEnd-to-end data encryption in transit
Data encryption at rest *Data encryption at rest *Data encryption at rest *
Secret managementSecret managementSecret management
Foundational CSPM *Foundational CSPM *Premium CSPM *
Static application security testing (SAST)Static application security testing (SAST)Static application security testing (SAST)
Infrastructure as code (IaC) scanningInfrastructure as code (IaC) scanningInfrastructure as code (IaC) scanning
Software composition analysisSoftware composition analysisSoftware composition analysis
Docker image security scanningDocker image security scanningDocker image security scanning
N/AKubernetes runtime protection *Kubernetes runtime protection *
N/AWeb application firewall (WAF) *Web application firewall (WAF) *
N/AN/ANetwork firewall *
- -

* Not available in the on-premises private data plane.

-
-

Tip

-

Available add-ons:
- - Security incident and event management (SIEM).
- - 24/7 security operation center.

-
- - - - - - -
-
- - -
- - - -
- - -
- - - -
-
-
- - - - - - - - - - - - - - - - - \ No newline at end of file diff --git a/en/site/references/troubleshoot-choreo/index.html b/en/site/references/troubleshoot-choreo/index.html deleted file mode 100644 index 7bce2480a..000000000 --- a/en/site/references/troubleshoot-choreo/index.html +++ /dev/null @@ -1,3535 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - Troubleshoot Choreo - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- - - -
- - - - - - -
- - -
- -
- - - - - - - -
-
- - - -
-
-
- - - - -
-
-
- - - -
-
-
- - - -
-
-
- - - -
-
- - - - - - - - - - - - - - - - - - - - -

Troubleshoot Choreo

-

This page walks you through common problems you may encounter when building and deploying components with Choreo, along with the recommended solutions to resolve each issue.

-

Troubleshoot component build errors

-
    -
  • -

    Deploying an Angular web application displays the Nginx welcome page instead of the application's homepage.

    -

    This occurs due to specifying an incorrect build output directory when you set up your Angular application in Choreo. -To resolve the issue, follow the guidelines given below:

    -
      -
    • Ensure that the build output directory correctly points to where your Angular build script outputs the files. The deafult output directory is dist/<project-name>.
      • -
    • Make sure to reconfigure the build settings if the current configuration is incorrect.
      • -
    -
    • -
  • -

    An error occurs in the container Trivy scan when building a BYOC component.

    -

    The recommended approach to address this issue is to fix the identified vulnerability and rebuild the component.

    -

    However, if you want to add a .trivyignore file to overcome the issue, ensure to add it to the Docker build context path specified when creating the component. For example, {buildContextPath}./trivyignore.

    -
    • -
  • -

    The config.js file is not properly mounted in a web application.

    -

    To resolve this issue, follow the steps given below:

    -
      -
    1. Add the config.js file to the app/public directory in your repository.
      2. -
    2. -

      Reference it from the index.html file by adding a script tag as follows:

      -

      <script src="public/config.js"></script>

      -
      3. -
    -
    • -
-

Troubleshoot component deployment errors

-
    -
  • -

    The config.js file is not properly integrated during the deployment of a React application, causing it to render with unexpected HTML instead of the expected JavaScript configuration.

    -

    To ensure correct loading of the config.js file, follow the steps given below:

    -
      -
    • -

      Reference the config.js file from the index.html file of your application by adding a script tag as follows:

      -

      <script src="public/config.js"></script>

      -
      • -
    • -

      Verify that the path in the script tag matches the location where the config.js file is stored in your repository.

      -
      • -
    • Make sure the script tag is placed within the <body> tag in your index.html file. You must ensure that it is not mistakenly placed within another HTML element.
      • -
    -
    • -
  • -

    I'm not aware of the commits that can trigger an automatic build in Choreo.

    -

    Merge commits and commits pushed directly to the branch can trigger a build in Choreo.

    -
    • -
-

Troubleshoot web application issues

-
    -
  • -

    After building a web application, the Nginx welcome page is displayed instead of the web application home page.

    -

    This can happen if an incorrect build output directory is specified during component creation.

    -

    During the build process, output files including the index.html are copied to the Nginx root directory. To ensure that the correct files are copied during the build process, you must check the Docker build logs.

    -
    • -
  • -

    The language I prefer to use is not available as a buildpack.

    -

    In such scenarios, you can use the Dockerfile buildpack to create the component.

    -
    • -
  • -

    I mistakenly used an incorrect build command when creating a web application. How can I update it before triggering a build?

    -

    You can go to the build page of the component and update the build command in the build configurations section.

    -
    • -
-

Troubleshoot managed-authentication issues

-
    -
  • -

    After securing a web application with managed authentication, I’m not able to add users who can sign in to the application.

    -

    For step-by-step instructions on how to manage users with Choreo's built-in identity provider (IdP), see Configure a User Store with the Built-In IdP.

    -

    For details on setting up other OpenID Connect (OIDC) supported IdPs, see Manage OAuth Keys.

    -
    • -
-

Troubleshoot Tailscale proxy issues

-
    -
  • -

    Where can I find logs to troubleshoot Tailscale proxy issues?

    -

    To troubleshoot Tailscale proxy issues, you can view the Runtime Logs of the running container for your Tailscale proxy deployment. These logs can help you diagnose most of the issues. - You can also view real-time container logs via the Runtime page under DevOps. For more details, see Observe real-time container logs.

    -
    • -
  • -

    I'm not able to connect the Tailscale proxy node to my Tailscale network due to an authentication failure.

    -
      -
    • -

      If you encounter the following log lines in your Tailscale proxy deployment, it indicates a misconfiguration of the TS_AUTH_KEY:

      -

      2024-06-04T10:38:53.885800940Z To authenticate, visit:
-2024-06-04T10:38:53.885802684Z 
-2024-06-04T10:38:53.885815708Z https://login.tailscale.com/a/696841f011517
-2024-06-04T10:38:53.885817457Z 
-2024-06-04T10:38:55.194344862Z Waiting for tailscale up to complete...
-2024-06-04T10:38:57.198970796Z Waiting for tailscale up to complete...
-2024-06-04T10:38:59.203265659Z Waiting for tailscale up to complete...
-
      -To resolve this, you must re-check your authentication key and ensure you have entered the correct key.

      -
      • -
    • -

      If you encounter the following log lines in your Tailscale proxy deployment, it indicates that your authentication key is invalid or expired. - 

      2024-06-04T11:33:58.762363181Z 2024/06/04 11:33:58 Received error: invalid key: unable to validate API key
-2024-06-04T11:33:58.762458209Z backend error: invalid key: unable to validate API key
-

      -

      To resolve this, you must verify the correctness of your authentication key. If the key has expired, you must generate a new key from Tailscale admin console.

      -
      • -
    -
    • -
  • -

    I'm not able to access private endpoints although the Tailscale proxy is properly connected to my Tailscale network.

    -

    To resolve this, do the following:

    -
      -
    • Ensure your on-premises setup is properly connected to the Tailscale network and that specific services, database servers, etc., are running as expected in your on-premises setup.
      • -
    • Verify that the IP addresses and ports specified in your Config.yaml file (mounted to Tailscale proxy during deployment) match the IP addresses in your Tailscale network.
      • -
    • Cross-check the ports defined in the endpoints.yaml file with the port mappings in the Config.yaml file.
      • -
    -
    • -
- - - - - - -
-
- - -
- - - -
- - -
- - - -
-
-
- - - - - - - - - - - - - - - - - \ No newline at end of file diff --git a/en/site/rest-api/index.html b/en/site/rest-api/index.html deleted file mode 100644 index 3702b71cb..000000000 --- a/en/site/rest-api/index.html +++ /dev/null @@ -1,15 +0,0 @@ - - - - - - Redirecting... - - - - - - -Redirecting... - - diff --git a/en/site/scheduled-tasks/index.html b/en/site/scheduled-tasks/index.html deleted file mode 100644 index 1e3d20c85..000000000 --- a/en/site/scheduled-tasks/index.html +++ /dev/null @@ -1,15 +0,0 @@ - - - - - - Redirecting... - - - - - - -Redirecting... - - diff --git a/en/site/search/search_index.json b/en/site/search/search_index.json deleted file mode 100644 index 2270d3abb..000000000 --- a/en/site/search/search_index.json +++ /dev/null @@ -1 +0,0 @@ -{"config":{"lang":["en"],"separator":"[\\s\\-]+","pipeline":["stopWordFilter"]},"docs":[{"location":"","title":"Home","text":"Welcome to the Choreo Learning Portal

NoteThe Home page will be designed to provide a guided experience to any user coming to docs with a valid Choreo use case. We intend to ONLY INCLUDE conceptual information in the documentation for the relevant topics and **NOT INCLUDE** any how to guides, or instructions with the exception of Tutorials.

"},{"location":"page-not-found/","title":"Page not found","text":"

Try one of the navigation links above or use the search engine in the top right corner.\u00a0

"},{"location":"what-is-choreo/","title":"What is Choreo?","text":"

Choreo is an internal developer platform that redefines how you create digital experiences. Choreo empowers you to seamlessly design, develop, deploy, and govern your cloud native applications, unlocking innovation while reducing time-to-market.

The following are some of the cutting-edge capabilities of Choreo:

  • Design that leads to end-to-end security, governance, and operational efficiency:

    • Domain-driven design: Organize your enterprise systems into domains, exposing managed APIs, events, and data through projects., A project consists of components representing units of deployment.
    • Application security design: Cell-based architecture, where projects become governable units from development to deployment, ensuring managed access via APIs, events, and data.

  • Efficient and effective development:

    • Code in any language: Develop applications in your team's preferred programming language, harnessing existing skill sets to build powerful polyglot APIs, services, events, tasks, and more.
    • Native support for VS Code: Seamlessly collaborate and manage code using VS Code in a feature-rich, visually-enhanced development environment.
    • Git repository integration: Effortlessly connect to Git-based platforms like GitHub, Bitbucket, or GitLab to develop components by linking an existing repository.

  • Seamless deployment:

    • CI/CD: Eliminate manual builds and unreliable deployments with Choreo's industry-standard CI/CD tooling, providing complete control and flexibility.
    • Multi-cloud Kubernetes: Easily deliver cloud native applications across Azure, AWS, GCP, or your Kubernetes clusters.
    • Configuration management: Centralize configuration parameters, sensitive credentials, and secrets across deployment environments via an intuitive interface.

  • Effortless management of APIs, integrations, microservices, and web applications:

    • Enable security: Empower security teams to manage data flows, ensuring seamless control over sensitive information like access credentials.
    • Scale up or down: Kubernetes handles scaling automatically, optimizing costs by scaling services based on demand.
    • Ensure reliability: DevOps and SRE teams can easily manage deployed components with built-in insights and observability.

  • Reusable digital assets:

    • Control visibility and sharing: Publish your digital assets to a shared marketplace for consumption by internal or external stakeholders, managed by role-based access control.
    • Internal Marketplace: Choreo's secure internal marketplace fosters transparency and efficiency with granular access control for publishers and consumers.

  • Comprehensive observability:

    • Anomaly detection: Stay ahead of issues with prompt notifications, ensuring balanced scaling and immediate action during unexpected mishaps.
    • Troubleshoot and debug: Quickly pinpoint and address root causes using detailed logs and data aligned in the same timeline, down to the machine-level details.

  • Robust governance:

    • DORA metrics: Monitor your DevOps efficiency with Choreo DORA metrics, experiencing rapid improvements in time from deployment to production safely and robustly.
    • Engineering insights: Gain visibility into engineering insights and advanced data analytics to make data-driven decisions, optimize processes, and improve efficiency.
    • API analytics: Understand API performance and adoption patterns to identify and resolve operational bottlenecks.
"},{"location":"administer/configure-a-custom-domain-for-your-organization/","title":"Configure a Custom Domain for Your Organization","text":"

A custom domain is essential for effective branding, discoverability, and credibility of a website. Choreo allows you to easily configure custom domains for your organization, enabling developers to utilize it to configure custom URLs for their components such as API proxies, services, web applications, and webhooks.

This section provides an overview of Choreo\u2019s custom domain configuration model and guides you through configuring a custom domain for your organization. It also walks you through utilizing a custom domain to configure a custom URL for a component.

"},{"location":"administer/configure-a-custom-domain-for-your-organization/#choreo-custom-domain-configuration-model","title":"Choreo custom domain configuration model","text":"

Choreo allows organization administrators to add custom domains for their organizations. When an administrator adds custom domains to an organization, component developers can submit requests to utilize the custom domains for their respective components. These requests require approval from the organization administrator. Upon approval, the custom domain and the relevant URL customization become available to the component.

"},{"location":"administer/configure-a-custom-domain-for-your-organization/#configure-a-custom-domain-for-an-organization","title":"Configure a custom domain for an organization","text":""},{"location":"administer/configure-a-custom-domain-for-your-organization/#prerequisites","title":"Prerequisites","text":"
  1. Sign in to the Choreo Console.

  2. Create an organization in Choreo.

"},{"location":"administer/configure-a-custom-domain-for-your-organization/#add-a-custom-domain","title":"Add a custom domain","text":"

To add a custom domain for your organization, follow the steps given below:

Note

To add a custom domain, you must have organization administrator privileges.

  1. Sign in to the Choreo Console.
  2. In the Choreo Console header, click the Organization list.
  3. In the left navigation menu, click Settings. This opens the organization-level settings page.
  4. Click the URL Settings tab and then click the Active Domains tab.
  5. Click + Add Domains.

  6. In the Add a Custom Domain pane, do the following:

    1. Enter your domain name.
    2. Select the environment to apply the domain name.

    3. Select the entity type to apply the domain name.

      Tip

      In this context:

      • The API entity type represents Choreo components exposed via an endpoint, including API Proxy, Service, and Webhook components.
      • The Web App entity type represents the Web Application component.

  7. Take a look at the generated CNAME target value displayed and create a DNS record associating the domain name to the CNAME target value with your DNS provider.

    Info

    When you select Developer Portal as the type, the environment is not applicable, and the CNAME alias will be displayed as follows:

  8. Once the CNAME type DNS record is created, click Verify.

    Note

    If the CNAME mapping is correct, the verification completes successfully. It can take some time for the configured CNAME mapping to be globally available.

  9. On successful verification of the custom domain, click Next.

  10. Select a TLS certificate provider depending on your preference. You can either import the TLS certificates you created for the custom domain or click Let's Encrypt to allow Choreo to generate and manage the certificates for you.

    If you want to import your own certificate, it should adhere to specific guidelines

    • TLS certificate guidelines:
      • It should be issued by a certificate authority (CA) and should contain the domain's public key along with additional information such as the domain name, the company that owns the domain, the certificate's expiration date, and the digital signature of the issuing CA.
      • It should be an X509 certificate.
      • It should be in the PEM format.
      • It should be issued directly or through a wildcard entry for\u00a0the provided custom URL. For example,
        • For direct issuance, the SSL file must include the exact domain name. For example, if the domain is apis.choreo.dev, the SSL file must include apis.choreo.com.
        • For wildcard entries, the SSL file should use a wildcard notation to cover all subdomains under the provided URL. For example, if the CNAME is apis.choreo.dev, the SSL file should use *.choreo.dev.
    • TLS key file guidelines:
      • It should be in the PEM format.
      • It must be encrypted using RSA encryption.
    • Certificate chain file guidelines:
      • The chain file, which is essential for some clients to verify the authenticity of a server's SSL/TLS certificate, should contain your domain's SSL/TLS certificate (optional, as this can be provided via the certificate itself) and one or more intermediate certificates in the correct order, leading back to a root certificate.
      • All certificates in the chain should be X509 certificates in PEM format.

    To proceed with this step in this guide, click Let's Encrypt.

  11. To save the custom domain, click Add.

Now, you have successfully added a custom domain for your organization.

You can see the added custom domain listed in the Active Domains tab under the URL Settings tab.

The custom domain you added will be available to the entity types in the specified environment. You can request the custom domain when configuring a custom URL for a component.

Note

If you add a custom domain for the Developer Portal type, the customization is applied immediately, and you can access the organization\u2019s Developer Portal via the added domain.

If you want to view the entity types that use a particular custom domain, click the specific custom domain listed in the Active Domains tab under URL Settings.

"},{"location":"administer/configure-a-custom-domain-for-your-organization/#configure-a-custom-url-for-a-component","title":"Configure a custom URL for a component","text":"

When an organization administrator adds custom domains for specific environments, developers can request any available custom domain to configure a custom URL for a component in a specific environment.

"},{"location":"administer/configure-a-custom-domain-for-your-organization/#request-a-custom-url-for-a-component","title":"Request a custom URL for a component","text":"

To request a custom URL for your component, follow the steps given below:

Note

Before you request a custom domain for a specific environment, ensure that the component is deployed to that environment.

  1. Sign in to the Choreo Console.
  2. In the Component Listing pane, click on the component for which you want to customize the URL.
  3. In the left navigation menu, click Settings. This opens the component-level settings page.

  4. Click the URL Settings tab. This displays the active deployments of the component across different environments and indicates whether a custom URL is configured. If an active custom domain is available to configure a custom URL for a component in a specific environment, the Edit URL Mapping icon in the corresponding Action column becomes enabled.

  5. To configure a custom URL for a component in a specific environment, click the Edit URL Mapping icon under the Action column corresponding to the respective environment. This opens the URL Settings dialog, where you can specify values to request for a custom URL.

  6. In the URL Settings dialog, select a domain to configure a custom URL.

    Tip

    • The Domain drop-down lists the available domains for the component. You can request for any listed domain.
    • If you want to request a custom URL for an API, you must specify an appropriate context path in the Path field. The Path field displays the default context path for the API. You can edit the path depending on your preference.

  7. Click Configure. This creates the custom URL mapping, which you can see under the URL Settings tab. The custom URL request will be in the Pending status until an organization administrator approves the request.

"},{"location":"administer/configure-a-custom-domain-for-your-organization/#approve-a-custom-url-request","title":"Approve a custom URL request","text":"

When a developer requests a custom URL, the request will be listed in the organization-level settings page under the URL Settings tab.

To approve a custom URL mapping, follow the steps given below:

Note

To approve custom URL requests, you must have organization administrator privileges.

  1. Sign in to the Choreo Console.
  2. In the Choreo Console header, click the Organization list.
  3. In the left navigation menu, click Settings. This opens the organization-level settings page.

  4. Click the URL Settings tab and then click the Pending URL Requests tab. You will see all the pending URL mapping requests sent by developers.

  5. Go to the custom URL you want to approve and click the corresponding Approve URL Mapping icon under the Action column.

  6. Review the details and click Approve.

Once approved, the invoke URL of the component gets replaced with the configured custom URL.

Now you have successfully utilized the configured custom domain to set up a custom URL for a component.

"},{"location":"administer/configure-a-user-store-with-built-in-idp/","title":"Configure a User Store with the Built-In Identity Provider","text":"

Developers looking to experiment with a complete application development process that includes user authentication and authorization can utilize Choreo's built-in identity provider (IdP). Choreo's built-in identity provider allows you to seamlessly test your application's authentication by setting up test users and groups within Choreo.

Note

Although the built-in IdP facilitates user management support, it is limited to adding users with attributes and groups. Therefore, the built-in IdP user management capabilities are not recommended for use in production.

"},{"location":"administer/configure-a-user-store-with-built-in-idp/#prerequisites","title":"Prerequisites","text":"

Before you try out the steps in this guide, be sure you have administrator rights to your Choreo organization. This permission is essential to configure a user store with the built-in IdP.

"},{"location":"administer/configure-a-user-store-with-built-in-idp/#configure-a-choreo-built-in-idp-user-store","title":"Configure a Choreo built-in IdP user store","text":"

Follow the steps given below to configure a Choreo built-in IdP user store for an environment:

  1. Go to https://console.choreo.dev/ and sign in.
  2. In the Choreo Console top navigation menu, click the Organization list and then click on your organization.
  3. In the left navigation menu, click Settings. This takes you to your organization settings.
  4. Click the Application Security tab and then click the Identity Providers tab.
  5. On the Identity Providers tab, click Manage in the Choreo Built-in Identity Provider pane.
  6. In the Manage IdP pane, click on a specific environment tab depending on where you want to configure the built-in IdP user store.
  7. You can download the sample User store template file(.csv ) from the User Store section. The template file content is similar to the following:
username,password,groups,first_name,last_name,email\n\"demouser\",\"password1\",\"[manager, engineering]\",\"John\",\"Doe\",\"john@acme.org\"\n

Note

The provided template file includes a sample user with associated attributes. To add new users, insert additional rows in the .csv file. To include more user attributes, add columns as required in the .csv file.

  1. Specify appropriate user details in the template file and save it.
  2. Select the template file that you saved and click Upload. A successful upload creates the user store and displays the configured users in the Users section.
"},{"location":"administer/configure-enterprise-login/","title":"Configure Enterprise Login","text":"

With Choreo, you can configure enterprise login to allow users from an external identity provider (IdP) to sign in to Choreo seamlessly without changing their credentials.

This guide walks you through the steps to configure enterprise login for your organization in Choreo.

"},{"location":"administer/configure-enterprise-login/#prerequisites","title":"Prerequisites","text":"

Before you proceed with the configuration, set up the following:

  • A valid email domain for your organization.
  • Access the Choreo Console at https://console.choreo.dev/ via your Google, GitHub, or Microsoft account. If you are a new user, create an organization with a unique organization name. For example, \"Stark Industries\".
"},{"location":"administer/configure-enterprise-login/#configure-enterprise-login-for-your-choreo-organization","title":"Configure enterprise login for your Choreo organization","text":"

To configure enterprise login for your Choreo organization, follow the steps given below:

  • If you already have a support account with us, send us your organization name/handle and the email domains specific to your organization through our support portal.

  • If you do not have a support account with us yet, send an email to choreo-help@wso2.com requesting to enable enterprise login for your organization.

    Tip

    Ensure you include the following information in the request:

    • Organization name or handle. For example, \u201cStark Industries\u201d or \u201cstarkindustries\u201d.
    • Email domains specific to your organization. For example, \u201c@stark.com\u201d, \u201c@starkindustries.com\u201d, and \u201c@stark.eu.

    Sample email

    Subject : [Stark Industries] Configure enterprise login

    Hi CS team,

    I need to configure enterprise login for my organization. Can you please do the necessary configurations to proceed?

    My organization details are as follows:

    • Organization name: Stark Industries
    • Organization handle: starkindustries
    • Email domains specific to my organization: \u201c@stark.com\u201d, \u201c@starkindustries.com\u201d, and \u201c@stark.eu\u201d

    Thank you.

    The Choreo support team will perform the necessary configurations and respond to you with a verification code. You must sign in to your domain host account and configure the DNS record for your email domain with the following values:

    Field Value Name/Host/Alias Specify @ or leave it blank Time to Live (TTL) Keep the default value or use 86400 Value/Answer/Destination wso2-domain-verification:<verification_code>

Now, you are ready to bring your own identity to Choreo.

"},{"location":"administer/configure-enterprise-login/#bring-your-own-identity-to-choreo","title":"Bring your own identity to Choreo","text":"

When you create an organization in Choreo, an organization with the same name is provisioned for you in Asgardeo. To bring your own identity to Choreo, you must configure a federated enterprise IdP on Asgardeo in the organization that is provisioned for you.

Follow the steps given below to configure the federated IdP:

  1. Sign in to Asgardeo.
  2. To configure a federated enterprise identity provider for your Asgardeo organization, follow the steps in Asgardeo documentation - Add Standard-Based Login.
  3. In the Asgardeo Console left navigation menu, click Applications. You will see an application named WSO2_LOGIN_FOR_CHOREO_CONSOLE.
  4. Click on the application to edit it.
  5. Click the Sign-in Method tab. You can observe the configured connection.

Now, users in your enterprise IdP can sign in to the Choreo Console using their enterprise IDs.

"},{"location":"administer/configure-enterprise-login/#configure-role-based-access-control-for-enterprise-login","title":"Configure role-based access control for enterprise login","text":"

To streamline the enterprise login process and grant appropriate permission, Choreo provides the flexibility to configure role-based access control for users who reside in an external IdP.

To set up role-based access control for enterprise login within Choreo, follow the steps given below:

"},{"location":"administer/configure-enterprise-login/#prerequisites_1","title":"Prerequisites","text":"

Before you proceed with the configuration, make sure you complete the following:

  1. Configure enterprise login for your organization. For instructions, see Configure enterprise login for your Choreo organization.
  2. Ensure your enterprise identity provider includes the group/role attributes in tokens it sends to Asgardeo via the respective protocol.
  3. Be sure you have administrator privileges in Choreo.
"},{"location":"administer/configure-enterprise-login/#step-1-configure-asgardeo","title":"Step 1: Configure Asgardeo","text":"
  1. Sign in to Asgardeo.

  2. Configure your IdP as an external IdP in Asgardeo. Depending on your IdP, you can select OpenID Connect or SAML as the protocol between Asgardeo and your IdP.

    Note

    If you are using OpenID Connect, configure the requested scopes accordingly for Asgardeo to get the relevant group/role details from the external IdP.

  3. To configure the application, follow the steps given below:

    1. In the Asgardeo Console left navigation menu, click Applications. You will see an application named WSO2_LOGIN_FOR_CHOREO_CONSOLE.
    2. Click on the application to edit it.
    3. Click the Sign-in Method tab.

    4. Configure the IdP for login depending on the protocol you selected:

      • For OpenID Connect, follow the instructions in Enable the OIDC IdP for login.
      • For SAML, follow the instructions in Enable the SAML IdP for login.

    5. Click the User Attributes tab.

    6. Select the Groups attribute and click the arrow to expand the section. Then, select the Requested checkbox.
    7. Click Update.

  4. To add the user attributes as OpenID Connect scopes, follow the steps given below:

    1. In the Asgardeo Console left navigation menu, click Scopes.
    2. In the OpenID Connect Scopes pane, click OpenID to edit it.
    3. Click New Attribute and select the Groups attribute.
    4. Click Save and then click Save Changes.
"},{"location":"administer/configure-enterprise-login/#step-2-map-choreo-groups-to-enterprise-idp-groups-via-the-choreo-console","title":"Step 2: Map Choreo groups to enterprise IdP groups via the Choreo Console","text":"

Note

Before you map Choreo groups to enterprise IdP groups, ensure you meet the following criteria:

  • Asgardeo is your key manager.
  • You have permission to perform actions of the organization administrator role.
  1. Sign in to the Choreo Console.
  2. In the Choreo Console, go to the top navigation menu and click Organization. This takes you to the organization's home page.
  3. In the left navigation menu, click Settings. This opens the organization-level settings page.
  4. In the Access Control tab, click Groups.

  5. Click Manage IdP Group Mapping.

  6. Click the edit icon corresponding to the Choreo group you want to map to the enterprise IdP group.

  7. In the IdP Group Name field, specify the exact name you configured in the enterprise IdP and enter to add it.

    Tip

    If there is a change to the IdP group mapping, it takes effect from the next login session onwards.

  8. Click Save.

By following these steps, you have successfully configured role-based access control for enterprise login in Choreo, allowing users from the external IdP to have the appropriate permission.

"},{"location":"administer/configure-self-sign-up/","title":"Configure Self-Sign-Up","text":"

With Choreo, you can set up a self-sign-up page for your Developer Portal. The self-sign-up page allows users to easily access your Developer Portal and subscribe to APIs. When you configure self-sign-up, users can create their accounts and access your Developer Portal without any manual intervention from you.

This page walks you through the steps to configure self-sign-up for your Developer Portal.

"},{"location":"administer/configure-self-sign-up/#prerequisites","title":"Prerequisites","text":"
  1. Sign in to the Choreo Console at https://console.choreo.dev/ using your Google, GitHub, or Microsoft account.
  2. If you are a new user, create an organization with a unique organization name. For example, \"Stark Industries\".
"},{"location":"administer/configure-self-sign-up/#configure-developer-portal-self-sign-up","title":"Configure Developer Portal self-sign-up","text":"

To configure self-sign-up, follow the steps given below:

  1. Send an email to choreo-help@wso2.com requesting to configure enterprise IdP for the Developer Portal of your organization.

    Tip

    Ensure you include the organization name or handle in the request.

    Sample email

    Subject : [Stark Industries] Configure enterprise IdP for Developer Portal

    Hi CS team,

    I need to configure enterprise IdP for my organization\u2019s Developer Portal to enable self-sign-up. Can you please do the necessary configurations to proceed?

    My organization details are as follows:

    • Organization name: Stark Industries
    • Organization handle: starkindustries

    Thank you

    The Choreo support team will perform the necessary configurations and respond to your request.

  2. When you receive a response, sign in to Asgardeo using the same credentials that you used to sign in to Choreo.

  3. In the Asgardeo Console, click View all applications.

    You will see an application named WSO2_LOGIN_FOR_CHOREO_DEV_PORTAL.

  4. Click on the application to edit it and enter your organization\u2019s Developer Portal URL as the Access URL of the application. For example, https://devportal.choreo.dev/starkindustries.

  5. Click Update.

  6. To add user attributes, follow these steps:

    Note

    If you have enabled enterprise login and you want to add the Groups attribute during self-sign-up configuration, avoid making it mandatory. This ensures proper access control and prevents unauthorized privileges. If you make the Groups attribute mandatory, it allows self-signed-up users to specify a group and assume roles associated with it.

    1. Click the User Attributes tab.

    2. To add the email as a mandatory user attribute, select Email and click the arrow to expand the section. Then, select the Requested and Mandatory checkboxes.

    3. To add the first name and last name as optional attributes, select Profile and click the arrow to expand the section. Then, select the Requested checkbox for the First Name and the Last Name attributes.

    4. Click Update.

  7. To add the user attributes as OpenID Connect scopes, follow these steps:

    1. In the Asgardeo Console left navigation menu, click Scopes.
    2. In the OpenID Connect Scopes pane, click OpenID to edit it.
    3. Click + New Attribute.
    4. Select Email, First Name, and Last Name as the attributes to associate with the OpenID scope.

    5. Click Save and then click Save Changes.

  8. To configure basic authentication as the sign-in method, follow these steps:

    1. In the Asgardeo Console left navigation menu, click Applications.
    2. In the Applications pane, click the WSO2_LOGIN_FOR_CHOREO_DEV_PORTAL application to edit it.

    3. Click the Sign-in Method tab and then click Start with default configuration.

    4. Click Update.

  9. To configure self-registration, follow these steps:

    1. In the Asgardeo Console left navigation menu, click Self Registration.
    2. In the Self Registration pane, click Configure.
    3. To enable self-registration, turn on the toggle.
    4. Select Account verification. This displays a confirmation message to enable account verification.
    5. Click Continue.
    6. Specify an appropriate value in the Account verification link expiry time field.

    7. Click Update.

Once you complete these steps, you will see a sign up link similar to the following in your Developer Portal:

Users can click LOGIN/SIGN UP and then click Create an account to sign up to access your Developer Portal.

"},{"location":"administer/configure-self-sign-up/#manage-new-users","title":"Manage new users","text":"

To manage users who want to access your Developer Portal via self-sign-up, you have two possible approaches:

  • Enable auto-approval for new user registrations: This approach automates the user approval process. When you enable auto-approval, each user who creates an account and signs up to your Developer Portal can access it by default.
  • Manually approve or reject user accounts: This allows you to review the list of user registrations and manually approve or reject each registration as needed.
"},{"location":"administer/configure-self-sign-up/#enable-auto-approval-for-new-user-registrations","title":"Enable auto-approval for new user registrations","text":"

To automatically approve each new user account registered on your Developer Portal, follow the steps given below:

  1. In the Choreo Console, click your username in the top right corner.
  2. In the drop-down menu, click Settings. This opens the Organization pane, where you can make necessary changes to organization settings.
  3. In the Organization pane, click Self Signups.
  4. To enable auto-approval, turn on the toggle.

Once you enable auto-approval, users can sign in to your Developer Portal and view your APIs and applications immediately after creating an account.

"},{"location":"administer/configure-self-sign-up/#manually-approve-or-reject-user-accounts","title":"Manually approve or reject user accounts","text":"

If you have not enabled auto-approval, you can manually approve or reject new user registrations. Once a user creates an account, Choreo sends an email to ask the user to confirm the account. To manually approve or reject user accounts, follow the steps given below:

  1. In the Choreo Console, click your username in the top right corner.
  2. In the drop-down menu, click Settings. This opens the Organization pane, where you can make necessary changes to organization settings.
  3. In the Organization pane, click Self Signups. You will see the user accounts listed for approval.

  4. To approve a user account, click Approve. To reject an account, click Reject.

    • If you approve an account, the user will receive an email confirming the approval.

    • If you reject an account, the user will receive an email mentioning that their account is rejected.

      Note

      A rejected user cannot sign up to your Developer Portal using the same account again.

"},{"location":"administer/control-access-in-the-choreo-console/","title":"Control Access in the Choreo Console","text":"

In the Choreo Console, you have the ability to manage access to projects and the actions that can be performed within them. Administrators have the capability to restrict project access to specific user groups. This feature is useful when you need certain user groups to have access to particular projects or for a set of projects.

Choreo uses Roles, Groups, and a Mapping level to control access to the Choreo Console as follows:

  • Role : Role is a collection of permissions. Choreo has a predefined set of roles with permissions assigned to them. Learn more

  • Group : Group is a collection of users. A user group requires a role or multiple roles to be assigned to it so that the users in those groups get the relevant permissions via the assigned roles. Learn more

  • Mapping level : A mapping level defines the extent at which a role-group mapping can be done. Choreo has two defined resource levels.

    • Organization : You can assign a role to a group or associate a group with a role within the organization. This ensures that all users in a group inherit the permissions granted by that role across all organizational resources. For example, if a user has edit_project permission at the organization mapping level, that user can edit all the projects in the organization.
    • Project : You can assign a role to a group or associate a group with a role within a specific project resource. This ensures that users in the group inherit the permissions granted by that role only within the context of the specified project. For example, If a user has edit_project permission at the project mapping level, that user can only edit the specified project.

In Choreo, authorization operates by assigning a role to a group at a specified level. The level at which the role is assigned determines the extent of permissions granted to users.

Important

Avoid assigning multiple roles to a single user across different projects or levels (organization and project). Such assignments can grant users unintended permission to some projects, allowing them to perform tasks they shouldn't have access to. Therefore, it is recommended to assign only one role to a user across projects or levels to ensure proper access control.

Info

In Choreo, organization-level permissions take precedence over project-level permissions.

To elaborate further, refer to the following diagram.

The following diagram depicts a role-group assignment at a specific resource level. In the diagram, an admin user has assigned the Developer role to all members of the Engineering group within the Engineering Project. This grants users in the Engineering group the ability to perform all actions allowed by the Developer role within the Engineering Project.

"},{"location":"administer/control-access-in-the-choreo-console/#sample-scenario","title":"Sample scenario","text":"

Now that you understand the basic concepts of access control within the Choreo Console, let\u2019s try out a sample scenario to manage access within a project.

Assume you are overseeing the Engineering Project within your organization and you need to grant development access to specific users solely within this project. Here's a step-by-step guide on how to achieve this:

"},{"location":"administer/control-access-in-the-choreo-console/#step-1-create-a-project","title":"Step 1: Create a project","text":"

Follow the steps given below to create a project:

  1. Go to https://console.choreo.dev/ and sign in. This opens the organization home page.
  2. On the organization home page, click + Create Project.

  3. Enter a display name, unique name, and description for the project. You can enter the values given below:

    Info

    In the Name field, you must specify a name to uniquely identify your project in various contexts. The value is editable only at the time you create the project. You cannot change the name after you create the project.

    Field Value Project Display Name Engineering Project Name engineering-project Project Description My sample project

  4. Click Create. This creates the project and takes you to the project home page.

"},{"location":"administer/control-access-in-the-choreo-console/#step-2-create-a-new-group","title":"Step 2: Create a new group","text":"

Follow the steps given below to create a group with the name Engineering Project Developer:

  1. In the Choreo Console, go to the top navigation menu, click the Organization list, and select the organization where you created your project.
  2. In the left navigation menu, click Settings.
  3. Click the Access Control tab and then click the Groups tab.
  4. Click + Create Group.

  5. Enter a group name and group description. You can enter the values given below:

    Field Value Group Name Engineering Project Developer Group Description Users with development access within the engineering project

  6. Click Create.

"},{"location":"administer/control-access-in-the-choreo-console/#step-3-assign-roles-to-the-group","title":"Step 3: Assign roles to the group","text":"

Follow the steps given below to assign the Developer role to the Engineering Project Developer group that you created:

  1. In the Choreo Console, go to the top navigation menu, click the Project list, and select the Engineering Project that you created.
  2. In the left navigation menu, click Settings.
  3. Click the Access Control tab and then click the Groups tab.
  4. On the Groups tab, search for the Engineering Project Developer group and click the corresponding edit icon.
  5. Click +Add Roles.
  6. In the Add Roles to Group in Project dialog that opens, click the Roles list and select Developer.

  7. Click Add. This assigns the Developer role to the group. You should see the mapping level as Project (Engineering Project) as follows, indicating the scope of the mapping:

This means that you have granted developer access to users in the Engineering Project Developer group in the scope of the Engineering Project.

Now that you have set up access control, you can proceed to add users to the new group.

"},{"location":"administer/control-access-in-the-choreo-console/#step-4-add-users-to-the-group","title":"Step 4: Add users to the group","text":"

There are two approaches you can follow to add users to the group.

Add a new user as a project developer

Follow the steps given below to add a new user as a project developer:

  1. In the Choreo Console, go to the top navigation menu, click the\u00a0Organization\u00a0list, and select the organization where you created your project.
  2. In the left navigation menu, click Settings.
  3. Click the Access Control tab and then click the Users tab.
  4. Click +Invite Users.
  5. In the Invite Users dialog,
  6. Specify the email addresses of the users in the Emails field.
  7. Click the Groups list and select Engineering Project Developer.
  8. Click Invite.
Add an existing user as a project developer

Follow the steps given below to add an existing user as a project developer:

  1. In the Choreo Console, go to the top navigation menu, click the\u00a0Organization\u00a0list, and select the organization where you created your project.
  2. In the left navigation menu, click Settings.
  3. Click the Access Control tab and then click the Users tab.
  4. Search for the existing user you want to add to the Engineering Project Developer group.
  5. Click the edit icon corresponding to the user.
  6. Click +Assign Groups.
  7. In the Add Groups to User dialog, click the Groups list and select Engineering Project Developer.
  8. Click Add.

Tip

Make sure to remove the user from any other groups to avoid granting organization-level access unintentionally.

Note

  • Existing groups are already mapped to similar roles at the organization level. Therefore, adding users to those groups or keeping users in them, will give organization-level access to the users.
  • When users are added to the Engineering Project Developer group, they will only have developer access to the Engineering Project.
  • You can invite new users or add existing users to new groups within the Engineering Project, and based on their requirements, assign roles like Developer, API Publisher, etc.

Now you have successfully set up access control within your project.

"},{"location":"administer/create-api-subscription-plans/","title":"Create API Subscription Plans","text":"

API subscription plans are essential to control and manage access to APIs. These plans define the rules and limitations on how clients can interact with APIs, ensuring efficient resource utilization and robust security. With the option to set rate limits and burst control, subscription plans allow API providers to manage traffic, prevent misuse, and offer tiered service levels. Organizations can implement subscription plans to provide varying levels of API access, accommodating different user needs and business models, while ensuring optimal performance and security.

In Choreo, users with the administrator role can create, update, and delete subscription plans at the organization level.

Tip

Deleting a subscription plan is only possible if there are no active subscriptions associated with it.

To create an organization-level subscription plan, follow the steps given below:

  1. Sign in to the Choreo Console.
  2. In the Choreo Console header, go to the Organization list and select your organization.
  3. In the left navigation menu, click Settings. This opens the organization-level settings page.
  4. Click the API Management tab and then click Subscription Plans.
  5. Click + Add Subscription Plan.

  6. In the Create Subscription Plan pane, enter the appropriate values for each field:

    Note

    • In the Name field, you must specify a name to uniquely identify the subscription plan in various contexts. The value is editable only at the time you create the subscription plan. You cannot change the name after you create it.
    • The Stop on Quota Reach checkbox is selected by default when creating a subscription plan. When selected, requests return an HTTP 429 response if the request count exceeds the limit. If you clear the checkbox, requests are allowed even if the quota is exceeded.
    • Burst control protects your backend from sudden request spikes and manages API usage. It\u2019s especially useful for subscription plans where the request count is enforced over a long period, to prevent consumers from using their entire quota too quickly. Ensure you select the Burst Control checkbox when the Request Count Time Unit is selected as Hour or Day.

  7. Click Create. This creates the subscription plan and lists it under Subscription Plans.

After creating subscription plans, users with the API publisher role can assign subscription plans to APIs. API consumers can then choose the appropriate subscription plan during the subscription process depending on their requirements.

"},{"location":"administer/customize-the-developer-portal/","title":"Customize the Developer Portal","text":"

The Developer Portal allows API consumers to find and consume APIs with ease. You can change the look and feel of your Developer Portal by changing the theme to match your brand. Doing so will help you give a better developer experience to your users.

To customize the Developer Portal theme, follow the steps given below:

Note

  • To customize the Developer Portal theme for an organization, you need to be an admin user of that organization.
  • You cannot undo a change and restore or revert to a previous version of the theme. However, you can reset it to the default theme.

  1. Sign in to the Choreo Console at https://console.choreo.dev/ using a Google/ GitHub/ Microsoft account.

  2. In the left pane, click Settings.

  3. In the header, click the Organization list. This will open the organization level settings page.

  4. In the API Management tab, click Devportal Theme.

    Once you access the theme, you can customize the Home page, color theme, font, header and footer, logos, etc., by expanding the relevant sections.

  5. Make a change to the theme. For example, let's change the title on the Home page and the color theme.

    1. To update the title on the Home page, expand the Home Page section, and in the Title field, change the default text (for example, to Try our APIs!).

    2. To update the color theme, expand the Color Palette section, and change the colors as required (for example, change the background color to #C3C5CD and the primary color of the buttons to #086634).

    3. Click Preview to view a preview of the Developer Portal with the changes you made. Based on the changes given in the examples, the preview appears as follows.

    4. Click Save to save your changes as a draft theme.

    5. To apply the changes to the Developer Portal, toggle the Go Live switch. To confirm that you want to go live with the changes, click Enable in the message that appears.

  6. Sign in to the Choreo Developer Portal at https://devportal.choreo.dev.

The Home page will appear as it did in the preview.

"},{"location":"administer/customize-the-developer-portal/#reset-the-developer-portal-theme","title":"Reset the Developer Portal theme","text":"

To reset the Developer Portal theme to the default theme, follow the steps given below:

  1. Sign in to the Choreo Console at https://console.choreo.dev/ using a Google, GitHub, or Microsoft account.

  2. In the left pane, click Settings.

  3. In the header, click the Organization list. This will open the organization level settings page.

  4. In the Organization tab, click Devportal Theme, and then click Reset to Default.

"},{"location":"administer/inviting-members/","title":"Inviting members","text":""},{"location":"administer/inviting-members/#inviting-users","title":"Inviting users","text":"

An organization administrator can invite users to the organization by assigning them specific groups. Invited users receive an invitation via email. An invited user must accept the invitation to join the organization and access the resources of that organization.

"},{"location":"administer/manage-members-of-an-organization/","title":"Manage Members of an Organization","text":"

An organization in Choreo is a logical grouping of users and user resources. A first-time user must create an organization and be a user of it when signing in to Choreo. Users and resources in an organization cannot access resources in another organization unless an admin of the other organization invites them and adds them as a user of that organization.

"},{"location":"administer/manage-members-of-an-organization/#inviting-users","title":"Inviting users","text":"

An organization administrator can invite users to the organization by assigning them specific groups. Invited users receive an invitation via email. An invited user must accept the invitation to join the organization and access the resources of that organization.

"},{"location":"administer/manage-members-of-an-organization/#manage-user-permission","title":"Manage user permission","text":"

For details on how Choreo manages user permission, see Manage user permission.

"},{"location":"administer/configure-an-external-idp/configure-asgardeo-as-an-external-idp/","title":"Configure Asgardeo as an External Identity Provider (IdP)","text":"

Asgardeo is an identity-as-a-service (IDaaS) solution designed to create seamless login experiences for your applications. Asgardeo seamlessly integrates with Choreo, providing powerful API access control through the use of API scopes. This enables restricting API access to designated user groups. By configuring Asgardeo as an external IdP in Choreo, you can leverage your Asgardeo user stores to manage API access control effectively. This guide walks you through the steps to set up Asgardeo as your external IdP.

"},{"location":"administer/configure-an-external-idp/configure-asgardeo-as-an-external-idp/#prerequisites","title":"Prerequisites","text":"

Before you proceed, be sure to complete the following:

  • Create an Asgardeo application. You can follow the Asgardeo guide to register a standard-based application.

  • Find the well-known URL: Go to the info tab of the Asgardeo application to view the endpoints and copy the Discovery endpoint.

  • Find the Client ID: Go to the Protocol tab of the Asgardeo application and copy the Client ID.

"},{"location":"administer/configure-an-external-idp/configure-asgardeo-as-an-external-idp/#add-asgardeo-as-an-external-idp-in-choreo","title":"Add Asgardeo as an external IdP in Choreo","text":"

Follow the steps below to add Asgardeo as an external IdP in Choreo:

  1. Sign in to the Choreo Console at https://console.choreo.dev/.
  2. In the left navigation menu, click Settings.
  3. In the header, click the Organization list. This opens the organization-level settings page.
  4. Click the Application Security tab and then click the Identity Providers tab.
  5. To add an identity provider, click + Identity Provider.
  6. Click Asgardeo.
  7. In the Asgardeo dialog that opens, specify a name and a description for the IdP.
  8. In the Well-Known URL field, paste the well-known URL that you copied from your Asgardeo instance by following the prerequisites.

  9. Leave the Apply to all environments checkbox selected. This allows you to use the tokens generated via this IdP to invoke APIs across all environments.

    Note

    If you want to restrict the use of tokens generated via this IdP to invoke APIs in specific environments, clear the Apply to all environments checkbox and select the necessary environments from the Environments list.

  10. Click Next. This displays the server endpoints that are useful to implement and configure authentication for your application.

  11. Click Add.

Now you have configured Asgardeo as an external IdP in Choreo.

"},{"location":"administer/configure-an-external-idp/configure-azure-ad-as-an-external-idp/","title":"Configure Azure Active Directory (Azure AD) as an External Identity Provider (IdP)","text":"

In organizations leveraging Microsoft Azure Active Directory (Azure AD) for identity and access management (IAM), integrating it with Choreo offers powerful API access control. This control hinges on the use of API scopes. That is, it enables the restriction of access to a designated group of users. This document guide you step-by-step to configure Azure AD as your external IdP.

"},{"location":"administer/configure-an-external-idp/configure-azure-ad-as-an-external-idp/#prerequisites","title":"Prerequisites","text":"

Before you try out this guide, be sure you have the following:

  • An Azure Active Directory account: If you don\u2019t already have one, setup an Azure Active Directory account at https://azure.microsoft.com/en-gb/.
  • Administrator rights to your Choreo organization: You need this to configure the Azure AD account in your organization.
"},{"location":"administer/configure-an-external-idp/configure-azure-ad-as-an-external-idp/#add-azure-active-directory-as-an-external-idp-in-choreo","title":"Add Azure Active Directory as an external IdP in Choreo","text":"

Follow the steps below to add Azure AD as an IdP in Choreo:

  1. Sign in to the Choreo Console at https://console.choreo.dev/.
  2. In the left navigation menu, click Settings.
  3. In the header, click the Organization list. This will open the organization level settings page.
  4. On the Application Security tab, click Identity Providers and then click + Identity Provider.
  5. Select Microsoft Entra ID (Azure AD) as the Identity Provider.
  6. Provide a name and a description for the IdP.

  7. To obtain the Well-Known URL of your Azure AD instance, on your Azure account, under Azure Active Directory go to App registrations, and then Endpoints. Copy the URI underOpenID Connect metadata document.

    Info

    • In azure, there are two versions of access tokens available. By default, the IDP applications you create use the v1 access token. Therefore, if you intend to use the v1 access token, when providing the Well-Known URL, omit the v2.0 path segment from the URL. Learn more For example, convert https://login.microsoftonline.com/<tenant-id>/v2.0/.well-known/openid-configuration-> https://login.microsoftonline.com/<tenant-id>/.well-known/openid-configuration
    • If you intend to work with v2.0, then the IDP application's manifest should be changed as explained in the access tokendocumentation.

  8. Leave the Apply to all environments checkbox selected. However, if you want to restrict the use of the external IdP to a certain environment, you can select them from the Environments list.

  9. Review the endpoints and click Next.
"},{"location":"api-management/api-policies/","title":"API Policies","text":"

API policies are units of business logic that you can apply to modify the flow of API invocations.

You can apply a policy to alter the Request, Response, or Error flow of an API invocation before it reaches the backend or the client. For example, you can add a policy to the response flow to transform the payload from JSON to XML and add a header to the response.

"},{"location":"api-management/api-policies/#inbuilt-mediation-policies","title":"Inbuilt mediation policies","text":"

Choreo supports a set of inbuilt mediation policies that can handle common API transformation and mediation tasks. These policies run within a single mediation service, making it straightforward to implement and manage complex mediation logic. The following inbuilt policies are available in Choreo:

  • JSON to XML: Transforms a JSON payload in a request or response into XML format. This policy is applicable only to JSON payloads in mediation flows. Applying it to a non-JSON payload terminates the flow. This policy cannot be used more than once on the same resource because the payload will already be converted to XML.
  • XML to JSON: Converts an XML payload in a request or response into JSON format. This policy is applicable only to XML payloads in mediation flows. Applying it to a non-XML payload terminates the flow. This policy cannot be used more than once on the same resource because the payload will already be converted to JSON.
  • Remove Query Parameter: Removes specified query parameters from a request. You can use this policy multiple times to remove different parameters. Attempting to remove a non-existent parameter has no effect. If the parameter exists, it will be removed; otherwise, the request proceeds as usual.
  • Remove Header: Removes specified headers from a request or response. You can attach this policy multiple times to remove multiple headers. The header name must be static, but you can use placeholders to configure different values for different environments. For example, ${headerName}.
  • Add Query Parameter: Adds query parameters to a request. You can attach this policy multiple times to add various parameters. Adding the same parameter multiple times creates an array of values. The parameter name and value must be static, but you can use placeholders to configure different values for different environments. For example, ${fooValue}.
  • Add Header: Adds headers to a request or response. If the same header is added multiple times, values are appended rather than overwritten. The header name and value must be static, but you can use placeholders to configure different values for different environments. For example, ${authzHeaderValue}.
  • Set Header: Sets headers in a request or response, overwriting any existing values. You can attach this policy multiple times to set multiple headers. Each time the same header is set, it replaces the previous value. The header name and value must be static, but you can use placeholders to configure different values for different environments. For example, ${authzHeaderValue}.
  • Rewrite Resource Path: Modifies the resource path of an HTTP request by replacing the original path with a new relative path. You can apply this policy multiple times, but only the last instance will take effect. The new path must be static, but you can use placeholders to configure different values for different environments. For example, ${myResourcePath}.
  • Log Message: Logs the payload and headers of a request or response. Attaching this policy multiple times results in duplicate log entries. By default, headers and payloads are not logged. To log them, you can enable Log Headers and Log Payload parameters. To exclude specific headers when logging, you can use the Excluded Headers parameter, which takes a comma-separated list of header names. An error will occur if payload logging is enabled but the payload cannot be read.

These inbuilt mediation policies provide flexibility to manage API requests and responses, allowing for custom transformations and logic without requiring custom code.

"},{"location":"api-management/api-policies/#attach-and-manage-mediation-policies","title":"Attach and manage mediation policies","text":"

You can easily attach one or more policies to an API proxy component implementation via the Choreo Console. If necessary, you can also rearrange or swap the policies you attach.

In Choreo, when you attach a mediation policy to a proxy, the deployment is a two-step process.

  1. Deployment initiation:

    If the component to which you want to attach the mediation policy is new, the system creates and commits a new repository with the mediation service code based on the attached policy. This new service is called the mediation application.

  2. Deploying the API:

    Once the deployment initiation is complete, you can specify configuration values if any, and proceed to deploy. Choreo builds the generated mediation application and pushes the Docker image to the Docker registry. Finally, Choreo deploys the mediation application with the API Proxy.

When a mediation policy is attached to a specific flow, the API invocation undergoes the following behavioral modification:

  • In the request path, the requests that pass through the gateway reach the relevant component, and Choreo executes any attached policies to the resource's request path before sending it to the backend.

  • In the response path, the mediation component receives response messages from the backend, and Choreo executes any mediation policies attached to the Response flow or the Error flow. Then the response is forwarded to the client.

  • If an error occurs during the execution of policies or due to an internal error, Choreo executes the Error flow and sends an error response to the client.

"},{"location":"api-management/api-policies/#attach-a-policy","title":"Attach a policy","text":"

To attach a policy to the Request, Response, or Error flow of a REST API proxy, follow the steps given below:

  1. Sign in to the Choreo Console.
  2. In the Component Listing pane, click on the REST API Proxy component for which you want to attach a policy.
  3. In the left navigation menu, click Develop and then click Policies.
  4. From the list of resources, expand the resource to which you want to attach the policy.
  5. Click Attach Mediation Policy in the respective flow for which you want to attach a policy.
  6. In the Policy List pane that opens, click on a required policy to view its details.

  7. If the attached policy requires parameter configuration, on the policy pane enter the appropriate values and configure the parameters. To make a parameter a configurable variable, input the value in the ${<variableName>} format. For example, you can use ${name} as an example.

  8. To attach the policy, click Add.

After attaching an API Policy, it is necessary to deploy the API for the policy to become active within its corresponding flow. To deploy the API follow the steps below:

  1. In the left navigation menu, click Deploy and then click Configure & Deploy. Choreo performs the mediation application generation step and opens the Configure & Deploy pane.

  2. In the Configure & Deploy pane, if you have any configurable variables that require values, specify appropriate values for them.

  3. Click Save & Deploy.

"},{"location":"api-management/api-policies/#refresh-mediation-policies","title":"Refresh mediation policies","text":"

Choreo selectively generates and builds the mediation application code during component deployment depending on specific changes. These changes include:

  • Addition, deletion, or modification of API resources.
  • Attachment, removal, or editing of API mediation policies.
  • Endpoint modifications via the Develop page.
  • Initial configuration or removal of backend endpoints or mutual TLS certificates.

If none of the above changes occur during deployment, Choreo skips the code generation and build process of the mediation application.

Info

  • If you want to enforce the code generation and build process of the mediation application in instances where the specified changes do not take place, you must turn on the Refresh Mediation Policies toggle when you configure and deploy the component.
  • It is useful to enable Refresh Mediation Policies when you want to incorporate the latest Ballerina patches for your generated mediation application. However, this can result in longer deployment times.
"},{"location":"api-management/api-policies/#implement-an-api-policy","title":"Implement an API policy","text":"

Choreo allows you to implement an API policy as a Ballerina project and attach it to an API proxy component.

Info

Supported Ballerina version: 2201.5.5

To implement a policy, follow the steps given below:

"},{"location":"api-management/api-policies/#prerequisites","title":"Prerequisites","text":"
  1. Set up Ballerina 2201.5.5.
  2. Open the ~/.ballerina/settings.toml file and ensure you have configured an access token to Ballerina Central. If you have not configured an access token, follow the steps given below to configure one:
    1. Generate a token via https://central.ballerina.io/dashboard?tab=token.
    2. Download the generated Settings.toml file and copy it to your local ~/.ballerina directory.

Alternatively, you can set the access token via the BALLERINA_CENTRAL_ACCESS_TOKEN environment variable.

export BALLERINA_CENTRAL_ACCESS_TOKEN=<access-token> \n
"},{"location":"api-management/api-policies/#step-1-initialize-a-ballerina-project","title":"Step 1: Initialize a Ballerina project","text":"

Choreo provides a template to initialize a mediation policy project with all the required configurations. The mediation policy project will be created as a Ballerina project.

To create a Ballerina project for the mediation policy using mediation.template as the project template, issue the following command:

Format:

    bal new -t choreo/mediation.template:1.0.0 <policy-name> \n

Example:

    bal new -t choreo/mediation.template:1.0.0 validateHeader \n
The Ballerina project that is created should have the following content:

Depending on your requirement, you can modify the Ballerina.toml and the Package.md files of the generated project. For example, you can update the org, package, package version, API documentation content, keywords, etc.

Note

To successfully publish to Ballerina Central, make sure you update the org value to your organization name.

     [package]\n        org = \"starkindustries\"\n        name = \"validateHeader\"\n        version = \"1.0.0\"\n        export = [\"validateHeader\"]\n        distribution = \"2201.5.5\"\n        keywords = [\"choreo-apim-mediation-policy\",\"choreo-apim-mediation-request-flow\",\"choreo-apim-mediation-response-flow\",\"choreo-apim-mediation-fault-flow\"]\n
"},{"location":"api-management/api-policies/#step-2-implement-the-policy","title":"Step 2: Implement the policy","text":"

In this step, you will implement the policy.

Let's assume you want to implement a policy to validate an incoming header in the request and the response.

  • Request path: If the request header is not present or if the validation fails, you want to log an error and return a 403 Bad Request response to the client.
  • Response path: You want to log a message to indicate whether the request is valid or not.

To implement the policy, open the policy.bal file in the Ballerina project and update the generated policy stubs(i.e., request, response, or fault) appropriately.

The following sections walk you through sample implementations for the Request and Response stubs:

Request flow

The following is a sample implementation for the request flow:

@mediation:RequestFlow\npublic function validateRequestHeader(mediation:Context ctx, http:Request req, string headerName, string headerValue) returns http:Response|false|error|() {\n   string|http:HeaderNotFoundError header = req.getHeader(headerName);\n   if (header is http:HeaderNotFoundError) {\n    string message = string `Header ${headerName} is not found`;\n    log:printError(message);\n    return generateResponse(message, http:STATUS_BAD_REQUEST);\n   }\n   if (header != headerValue) {\n    string validationFailedMessage = string `Header validation failed. Expected ${headerValue} but found ${header}`;\n    log:printError(validationFailedMessage);\n    return generateResponse(validationFailedMessage, http:STATUS_BAD_REQUEST);\n    }\n    log:printInfo(\"Header validation successful\");\n    return ();\n};\n\nfunction generateResponse(string message, int statusCode) returns http:Response {\n    http:Response response = new();\n    response.setTextPayload(message); \n    response.statusCode = statusCode;\n    return response;\n}\n
Response flow

The following is a sample implementation for the response flow:

@mediation:ResponseFlow\npublic function validateResponseHeader(mediation:Context ctx, http:Request req, http:Response res, string headerName, string headerValue) returns http:Response|false|error|() { \n   string|http:HeaderNotFoundError header = res.getHeader(headerName);\n   if (header is http:HeaderNotFoundError) {\n    string message = string `Header ${headerName} is not found`;\n    log:printError(message);\n    return ();\n   }\n   if (header != headerValue) {\n    string validationFailedMessage = string `Header validation failed. Expected ${headerValue} but found ${header}`;\n    log:printError(validationFailedMessage);\n    return ();\n   }\n   return ();\n}\n
Fault flow

In this guide, you are not going to make any changes to the Fault flow. Therefore, you can remove the Fault flow stub from the policy.bal file.

Note

The @mediation:RequestFlow, @mediation:ResponseFlow, and @mediation:FaultFlow annotations are bound with the keywords in the Ballerina.toml. Therefore, the changes you make to the policy stubs should reflect in the Ballerina.toml file. For example, if the policy is applicable only on the request and response paths, you can remove the @mediation:FaultFlow annotation from the policy. Then, you MUST also remove the choreo-apim-mediation-fault-flow keyword from the generated Ballerina.toml file. If you do not do so, the Ballerina compiler will show an error at compile time.

Publish as a private custom policy

Choreo supports publishing a policy as a private custom policy. Publishing a policy as a private custom policy makes the policy inaccessible outside of the organization. To publish a policy as a private custom policy, change the visibility to private prior to pushing the package to Ballerina Central as follows:

  1. Open the Ballerina.toml file of your policy.

  2. Set the visibility to private by adding the configuration visibility=\"private\". For example:

    [package]\n   org = \"orgName\"\n   name = \"packageName\"\n   version = \"1.0.2\"\n   export = [\"packageName\"]\n   distribution = \"2201.5.5\"\n   keywords = [\"choreo-apim-mediation-policy\",\"choreo-apim-mediation-request-flow\",\"choreo-apim-mediation-response-flow\",\"choreo-apim-mediation-fault-flow\"]\n   visibility = \"private\"\n

  3. Package and publish your policy to Ballerina Central.

Best practices

When implementing a policy, it is essential to follow best practices to ensure efficiency and maintainability. Here are some recommended best practices to follow:

  • Organize the source code within the default module of the package. Do not add any additional modules.
  • A policy implementation can contain any combination of flows. A generated project contains stubs for all three flows: Request, Response, and Fault. You can remove any stub that you do not require. For example, when you create a policy that re-writes the resource paths, you can remove the Response and fault stubs.
  • The HTTP request/response objects and context record parameters gets passed as references to the policy functions. Therefore, the changes you make to these values persist throughout the policy execution and are propagated to subsequent policies. This behavior allows the request and response objects to accumulate transformations applied by attached policies.
  • Familiarize yourself with the different return types of policy flows. The following return types are unmodifiable:
    • http:Response - Returns an HTTP response when you terminate the mediation flow prematurely. For example, in the in-flow sequence, the mediation sequence terminates before calling the backend. The mediation policy then sends an HTTP response to the client.
    • false - Returns false if you want to terminate the mediation sequence with a predefined response (on the Choreo side).
    • error - Returns an error if you want to terminate the mediation flow and transfer control to the fault flow. The fault flow would then construct an error response and send it to the client.
    • () - Returns () to signal the successful completion of the policy. Once the proxy has completed executing the policy, it starts to execute the next policy in the sequence.
"},{"location":"api-management/api-policies/#step-3-publish-the-policy","title":"Step 3: Publish the policy","text":"

Once you implement a policy, you must publish it to Ballerina Central.

When you attach a policy and deploy an API, Choreo pulls the necessary packages from Ballerina Central and bundles them into the mediation application under the hood. Therefore to use policies in your APIs, you must publish them as public packages.

To publish the policy, follow the steps given below:

  1. To package the policy before you publish it to Ballerina Central, issue the following command: 
        bal pack \n

  2. To publish the package to Ballerina Central, issue the following command:

        bal push \n

Once you publish the package, it will appear as follows in the policy list:

"},{"location":"api-management/api-policies/#write-unit-tests","title":"Write unit tests","text":"

You can write unit tests to test policy functions in a manner similar to how you write unit tests for a regular Ballerina function.

The following is a sample unit test for the validateRequestHeader function:

import ballerina/http;\nimport choreo/mediation;\nimport ballerina/test;\n\n@test:Config {}\npublic function testRequestHeaderValidationFailure() {\n  http:Request req = new;\n  http:Response|false|error|() result = validateRequestHeader(createContext(\"get\", \"/test\"), req, \"testHeader\", \"test\");\n\n  if !(result is http:Response) {\n    test:assertFail(\"Expected http:Response, found \" + (typeof result).toString());\n  }\n\n  test:assertEquals(result.statusCode, http:STATUS_BAD_REQUEST, \"Status code mismatch\");\n}\n\nfunction createContext(string httpMethod, string resPath) returns mediation:Context {\n   mediation:ResourcePath originalPath = checkpanic mediation:createImmutableResourcePath(resPath);\n   mediation:Context originalCtx =\n               mediation:createImmutableMediationContext(httpMethod, originalPath.pathSegments(), {}, {});\n   mediation:ResourcePath mutableResPath = checkpanic mediation:createMutableResourcePath(resPath);\n   return mediation:createMutableMediationContext(originalCtx, mutableResPath.pathSegments(), {}, {});\n}\n

The policy function modifies the same request/response/context instance that you pass to it. You can check the request/response/context instance after calling the policy function to verify changes.

"},{"location":"api-management/api-policies/#glossary","title":"Glossary","text":"

Here are some of the common terms used when working with policies in Choreo:

mediation:Context

The mediation context is used to pass parameters between policies. It is created per request and you can access it in any of the flows. For example, if a correlation ID needs to be set to the request, you can set it in the context of the request flow and access it in the response or fault flow.

The mediation context can include the following functions:

# Retrieves the value for the specified key.   \npublic function get(string name) returns anydata;\n\n# Stores the provided key-value pair. If a mapping exists for the key, the value is overwritten.\npublic function put(string name, anydata value);\n\n# Removes the entry mapped by the specified key and returns the removed value.\npublic function remove(string name) returns anydata;\n\n# Retrieves the value for the specified key. If there is no mapping for the key, return the specified\npublic function getOrDefault(string name, anydata default) returns anydata;\n\n# Checks whether a mapping exists for the specified key.\npublic function hasKey(string name) returns boolean;\n\n# Returns the `mediation:Context` instance which captured the initial contextual information of the resource,\n# before the mediation flow was invoked. Calling this on an original `mediation:Context` object will return itself.\npublic function originalContext() returns Context;\n\n# The HTTP method of the resource method\npublic function httpMethod() returns string;\n\n# Retrieves an instance of `mediation:ResourcePath` which is an API for contextual information on the resource path\n# of this resource. It also contains methods for modifying the resource path as the user sees fit. This resource\n# path is the same path used by the mediation service for deriving the backend endpoint's resource to invoke.\n# Therefore, the default behavior of the mediation service is to invoke a resource in the backend endpoint which\n# has the same relative resource path as the corresponding mediation service resource.\npublic function resourcePath() returns ResourcePath;\n\n# Sets the given `mediation:ResourcePath` instance as the resource path of this context.\npublic function setResourcePath(ResourcePath path);\n\n# Adds a mapping between a path param name and a resolved value for it. There need not be a path parameter in the\n# resource path by the name specified in `name` for one to use this method. On its own, the path param values have\n# no bearing on the resource path.\npublic function addPathParamValue(string name, PathParamValue value);\n\n# Returns the collection of resolved values for the path parameters in this particular context, mapped\n# by the parameter name.\npublic function resolvedPathParams() returns map<PathParamValue> & readonly;\n\n# Removes the resolved path parameter value which maps to the specified name.\npublic function removePathParamValue(string name);\n\n# Adds a query parameter to the request to be sent to the backend. If there is already a query parameter by\n# with the same name, the new value will be appended to it, making it an array.\npublic function addQueryParam(string name, string value);\n\n# Removes the specified query parameter from the request. If the value of the parameter is an array, the whole\n# array will be removed.\npublic function removeQueryParam(string name);\n\n# Retrieves a map of all the query parameters in the current request context. The returned map is a read-only snapshot\n# of the map of query parameters in the context at the time this method was called.\npublic function queryParams() returns map<string[]> & readonly;\n
"},{"location":"api-management/api-policies/#keywords","title":"Keywords","text":"

The Ballerina.toml file needs to include the following keywords for the mediation policies to work:

  • choreo-apim-mediation-policy: This keyword is a mandatory keyword that is required to identify that the package is a mediation policy type.
  • choreo-apim-mediation-request-flow: Specifies whether the policy applies to the request flow.
  • choreo-apim-mediation-response-flow: Specifies whether the policy applies to the response flow.
  • choreo-apim-mediation-fault-flow: Specifies whether the policy is applicable for the fault flow.
Policy name and description

The Package.md file contains information about the policy. Choreo uses this information to render the policy configuring UI. This file is written in Markdown format and should be structured as follows.

Format:

# <policy-name>\n\n## Overview\n\n<policy description>\n

Example:

# ValidateHeader\n\n## Overview\n\nThis policy validates the request and response headers with the configured values.\n
Policy versioning

When it comes to policy versioning in Choreo or mediation dependencies, it is important to consider the major version changes in the Ballerina language. For example, transitioning from update 1 to update 2 requires a major version increment, which can introduce significant incompatibilities.

Therefore, to ensure compatibility, the recommended approach is to version the policy package in a manner that the major version gets upgraded when the Choreo/mediation dependency version is upgraded to a major version.

"},{"location":"api-management/api-rate-limiting/","title":"API Rate Limiting","text":"

API rate limiting is a technique that allows you to control the rate of requests made to an API. Rate limiting helps prevent system overload and enhances API performance. When you limit the number of requests that can be made in a specific time frame, you can ensure that your API is available and responsive to all users while protecting it from malicious attacks.

This page walks you through the steps to enable rate limiting for your APIs via Choreo and also provides information on the rate-limiting options supported by Choreo.

"},{"location":"api-management/api-rate-limiting/#enable-rate-limiting-for-an-api","title":"Enable rate limiting for an API","text":"

To enable rate limiting for an API, follow the steps given below:

Note

You can apply rate-limiting settings separately for each environment.

  1. Sign in to the Choreo Console.
  2. In the Component Listing pane, click on the component for which you want to apply rate limiting.
  3. In the left navigation menu, click Deploy.

  4. Go to the required environment card and click the view icon corresponding to the endpoint for which you want to apply rate limiting.

    Info

    If you are applying rate limiting for an API Proxy component, go to the required environment card, click the setting icon corresponding to API Configuration, and proceed to step 6.

  5. In the Endpoint Details pane that opens, click the settings icon.

  6. In the Manage section, click Rate Limiting to expand it.
  7. Select a Rate Limiting Level depending on your requirement and click Apply.
"},{"location":"api-management/api-rate-limiting/#api-level-rate-limiting","title":"API-level rate limiting","text":"

API-level rate limiting applies the allocated request count for the specified time unit to all operations in the API.

"},{"location":"api-management/api-rate-limiting/#operation-level-rate-limiting","title":"Operation-level rate limiting","text":"

Operation-level rate limiting allows you to configure different rate-limiting values for each operation. You can use this option to define specific rate-limiting values for critical API operations that require an extra layer of protection.

"},{"location":"api-management/api-rate-limiting/#rate-limiting-response-headers","title":"Rate-limiting response headers","text":"

The following table lists the response headers available when you enable rate limiting for your APIs. You can implement necessary rate-limiting scenarios depending on the response header values.

Header Name Description x-ratelimit-limit Denotes the request count allocated for the specified time unit. x-ratelimit-reset Provides the time remaining to start the next rate-limiting time unit. x-ratelimit-remaining Denotes the remaining request count for the specified time unit. x-ratelimit-enforced Visible after exceeding the allocated request count."},{"location":"api-management/control-api-visibility/","title":"Control API Visibility","text":"

By default, the APIs published in Choreo are visible to anyone who visits the Choreo Developer Portal. By default, Choreo sets the visibility of the API to Public. However, developers can control the visibility of their APIs by changing the default option to Private or Restricted.

Visibility settings control users from viewing and modifying APIs. API visibility can be one of the following options:

  • Public : The API is visible to all in the developer portal.

  • Private : The API is visible to the users who only sign in to the Developer Portal.

  • Restricted: The API is visible to only the user that has the roles that you specify. This option helps developers to enforce fine-grained access control to the API.

"},{"location":"api-management/control-api-visibility/#change-api-visibility","title":"Change API visibility","text":"
  1. Sign in to the Choreo Console.
  2. In the Component Listing pane, click on the REST API (Service) for which you want to control API visibility.
  3. In the left navigation menu, click Manage and then click API Info.
  4. On the API Info page that opens, click the Developer Portal tab.

  5. Under General Details, select the required visibility setting from the Visibility list.

    Enable fine-grained role-based access control to the API

    1. To enable fine-grained role-based access control to an API in the Developer Portal, select Restricted from the API visibility list. Once selected, you will see the roles available in your organization in the Visible Roles list.
    2. Select any combination of roles. Only the users with the given roles can access the APIs through the Dev Portal.
    3. Alternatively, You can create a new role and assign it to an API by following the steps below:
      1. Click + Create New Role in the list.
      2. Add the role name and description.
      3. Click Next.
      4. Assign the relevant permissions to the new role.
      5. Click Create.
      6. Select the newly created role from the Visible Roles list.

  6. Click Save.

"},{"location":"api-management/documents/","title":"Documents","text":"

When an API consumer signs in to the Choreo Developer Portal to browse APIs, it is not sufficient to just have an API thumbnail along with the name and version of the API. An API consumer would expect to see more details about the API, such as the following:

  • A brief description of the API.
  • How to invoke the API.
  • The limitations/restrictions of the API.
  • Version history.

To provide such information that improves the overall visibility of the API, an API developer can add such documentation to an API before publishing it to the Developer Portal.

"},{"location":"api-management/documents/#add-documents-to-an-api","title":"Add documents to an API","text":"

To add documentation for an API, follow the steps given below.

  1. Sign in to the Choreo Console.

  2. In the Component Listing pane, click on the component for which you want to add documents.

  3. In the left navigation menu, click Manage and then click Documents.

  4. Specify a title for the document and provide the content in markdown syntax.

  5. Click Add to save the document.

Depending on the information you need to add to the API, you can add one or more documents.

You can also edit existing documents and delete documents if necessary.

"},{"location":"api-management/lifecycle-management/","title":"Lifecycle Management","text":"

API lifecycle management is an important aspect of API management. The API lifecycle consists of various states that an API passes through, from creation to retirement. In Choreo, there are six distinct lifecycle states: created, pre-released, published, blocked, deprecated, and retired.

By leveraging the various lifecycle states, API managers can optimize the development process and ensure that subscribers have access to the latest and most reliable APIs.

"},{"location":"api-management/lifecycle-management/#api-lifecycle-states","title":"API lifecycle states","text":"

The following lifecycle states are applicable to APIs in Choreo:

API lifecycle state Use case Corresponding action CREATED The API is created but is not ready for consumption. The API is not visible to subscribers in the Developer Portal. PRE-RELEASED A prototype is created for early promotion and consumer testing. You can deploy a new API or a new version of an existing API as a prototype to provide subscribers with an early implementation of the API. The API is published to the Developer Portal as a pre-release. PUBLISHED The API is ready for subscribers to view and subscribe to via the Developer Portal The API is visible in the Developer Portal and is available for subscription. BLOCKED Access to the API is temporarily blocked. Runtime calls are blocked, and the API is not visible in the Developer Portal. DEPRECATED The old version of an API is moved to this state when a newer version of the API is PUBLISHED. The API is deployed and is available to existing subscribers. New subscriptions are disabled. Existing subscribers can continue to use it as usual until the API is retired. RETIRED The API is no longer in use when it is in this state. The API is unpublished and deleted from the Developer Portal."},{"location":"api-management/lifecycle-management/#manage-the-lifecycle-of-an-api","title":"Manage the lifecycle of an API","text":"

To change the lifecycle state of an API via the Choreo Console, follow the instructions given below:

Tip

You must have publishing privileges to manage the lifecycle states of a component.

  1. Sign in to the\u00a0Choreo Console.
  2. In the Component Listing pane, click on the component for which you want to manage the lifecycle.
  3. In the left navigation menu, click\u00a0Manage, and then click Lifecycle.
  4. In the Lifecycle Management pane, you will see the lifecycle state transition diagram indicating the current lifecycle state of the component. Just above the lifecycle state transition diagram, The possible lifecycle states you can apply to the component are displayed just above the lifecycle state transition diagram. Click on a required lifecycle state to apply it to the component. For example, if a component is in the Created state, you can click either Pre-release or Publish.
"},{"location":"api-management/rename-api-display-name/","title":"Rename API Display Name","text":"

Choreo allows you to make one or more endpoints accessible through its service and integration components. These endpoints are published as individual APIs in Choreo, accessible via the Choreo Developer Portal. By default, Choreo assigns an API name by combining the component name and the endpoint name, resulting in the following format: <component name>-<endpoint name>. For example, if you create a component named Ballerina Reading List, the API is displayed as Ballerina Reading List - GraphQL Reading List 591.

Choreo provides you with the flexibility to personalize the display name of the API, enhancing its user-friendliness and readability. Once you modify the API display name within the Choreo Console, Choreo applies the change immediately. From there onwards, Choreo displays the published API by this name in the Choreo Developer Portal.

Follow the steps below to rename the API display name:

  1. Go to https://console.choreo.dev/ and sign in. This opens the project home page.
  2. In the Component Listing pane, click on the component for which you want to rename the API display name. This opens the Overview page of the component.
  3. In the left navigation menu, click Manage and then click API Info.
  4. On the API Info page that opens, click the Developer Portal tab.
  5. Under General Details, specify an appropriate API display name in the Name field.
  6. Click Save.

Now, you can view the updated API display name in the Choreo Developer Portal.

"},{"location":"api-management/manage-api-traffic/assign-subscription-plans-to-apis/","title":"Assign Subscription Plans to APIs","text":"

API subscription plans allow API publishers to control and manage access to APIs. These plans define the rules and limitations on how clients can interact with APIs, ensuring efficient resource utilization and robust security.

Choreo allows users with the administrator role to create, update, and delete subscription plans at the organization level. For instructions on creating subscription plans, see Create API Subscription Plans.

Once created, Choreo allows API publishers to assign subscription plans to APIs, providing different levels of access based on user needs.

To assign subscription plans to an API, follow the steps given below:

  1. Sign in to the Choreo Console.
  2. In the Component Listing pane, click on the component for which you want to assign subscription plans.
  3. In the left navigation menu, click Manage and then click Subscription Plans. This displays the subscription plans available for the component.

  4. Enable the Subscription Plan Status toggle corresponding to the subscription plans you want to assign to the API.

  5. Click Save.

When an API has subscription plans assigned to it, API consumers can select the plan that best fits their requirements during the subscription process. For details, see Subscribe to an API with a Subscription Plan

"},{"location":"api-management/manage-api-traffic/subscribe-to-an-api-with-a-subscription-plan/","title":"Subscribe to an API with a Subscription Plan","text":"

If an API has subscription plans assigned to it, API consumer can select the subscription plan that best fits their requirement at the time of subscribing to the API.

To subscribe to an API with a subscription plan, follow the steps given below:

  1. Sign in to the Choreo Developer Portal.
  2. In the Developer Portal header, click Applications.
  3. On the My Applications page, click on the application you want to use to subscribe to an API.
  4. In the left navigation menu, click Subscriptions.
  5. In the Subscription Management pane that opens, click + Add APIs.
  6. In the Add APIs pane that opens, select the API, API version, and subscription plan with which you want to subscribe to the API.

  7. Click Add Subscription.

To verify that the subscription plan works as expected, follow the steps given below:

  1. In the Developer Portal header, click APIs.
  2. Search for the API you subscribed to and click Try Out.

  3. Invoke the API until you exceed the request limit set in the subscription plan. You will see that the API throttles further requests once the limit is reached.

"},{"location":"authentication-and-authorization/configure-mutual-tls-between-components/","title":"Configure Mutual TLS Between Components","text":"

Mutual transport layer security (mutual TLS) is a protocol that ensures privacy, integrity, and authentication of the data transmitted between two endpoints. In mutual TLS, the client and the server authenticate each other using digital certificates, establishing trust and verifying identities. Upon successful authentication, mutual TLS encrypts the data exchanged between the client and the server, preventing unauthorized access.

In Choreo, you can use mutual TLS to establish secure connections between components within a project.

Note

If mutual TLS is not required, you can configure TLS instead. TLS provides a secure communication channel between a client and server but does not require the client to present a certificate to the server. This results in the absence of mutual authentication between the client and the server. While TLS ensures the confidentiality of data transmitted between the client and server, preventing unauthorized tampering, mutual TLS enhances TLS by introducing client-side authentication and facilitating mutual verification of identities between the client and server.

To configure TLS, you can follow the same steps as for mutual TLS as mentioned below, without having to generate a client certificate. The client only needs the root certificate to verify the server's identity.

"},{"location":"authentication-and-authorization/configure-mutual-tls-between-components/#generate-certificates-to-establish-mutual-tls","title":"Generate certificates to establish mutual TLS","text":"

  • Root certificate: Trusted by both the client and the server, this certificate is used to verify the authenticity of other certificates presented during the mutual TLS handshake process and to issue certificates for clients and servers. For a specific project, you can generate a single root certificate using a tool like OpenSSL.

  • Client certificate: Contains the client\u2019s identity for authentication. The common name (CN) in the certificate identifies the client. The generated client certificate must be signed by the root certificate.

  • Server certificate: Clients use the server certificate to verify the trustworthiness of the server and establish a secure and authenticated connection. Similar to the client certificates, the server certificate must also be signed by the root certificate. When generating the server certificate, you must specify the server's hostname for the subject alternative name (SAN). You can obtain the hostname for the specific version of a service component from any project endpoint on the Overview page.

For example, if your project endpoint is http://my-service-3781140846:7080/todos, the hostname will be my-service-3781140846.

"},{"location":"authentication-and-authorization/configure-mutual-tls-between-components/#read-mutual-tls-certificates-from-your-component","title":"Read mutual TLS certificates from your component","text":"

The approach to read mutual TLS certificates from a component can vary depending on its implementation. Typically, a component can read the certificate data from the file system or via an environment variable. For detailed instructions on adding environment variables and file mounts to your application, see Manage Configurations and Secrets.

Info

When you specify a private key, ensure you save it as a secret.

"},{"location":"authentication-and-authorization/configure-mutual-tls-between-components/#sample-for-mutual-tls-communication","title":"Sample for mutual TLS communication","text":"

For a sample that demonstrates how you can deploy services that communicate using mutual TLS, see service-to-service-mtls.

"},{"location":"authentication-and-authorization/pass-end-user-attributes-to-upstream-services/","title":"Pass End-User Attributes to Upstream Services","text":"

There are scenarios where a backend service needs to apply specific logic or make decisions depending on the user consuming an API. In such scenarios, you must pass end-user attributes to the backend during an API call.

Choreo provides a method to send user information to a backend service through a JSON Web Token (JWT) in an HTTP header of an API request.

"},{"location":"authentication-and-authorization/pass-end-user-attributes-to-upstream-services/#how-it-works","title":"How it works","text":"

The backend JWT contains claims transferred between the parties, such as the user and the backend. A claim can be metadata of the request or data about the user. A set of claims is called a dialect, for example, http://wso2.org/claims.

For each API request, a digitally signed JWT is carried to the backend service in the following format to ensure that the authenticity of the claims list is verified:

{token header}.{claims list}.{signature}

When a request goes through Choreo, the backend JWT is appended as the\u00a0X-JWT-Assertion\u00a0header in the outgoing message. The backend service fetches the JWT and retrieves the required information about the user, application, or token.

"},{"location":"authentication-and-authorization/pass-end-user-attributes-to-upstream-services/#claims","title":"Claims","text":"

Claims are fragments of information included in the JWT.

The following is a sample claim set added to the end-user token for an access token generated via the authorization code:

Tip

This access token is generated via Asgardeo using the authorization code grant type. Here, the Asgardeo application is configured to include the email claim in the token. 

{\n\"sub\": \"11f53c32-f8ac-4810-bb79-615b2184baf5\",\n\"http://wso2.org/claims/apiname\": \"JWT Test - Endpoint 9090 803\",\n\"http://wso2.org/claims/applicationtier\": \"Unlimited\",\n\"http://wso2.org/claims/version\": \"1.0.0\",\n\"http://wso2.org/claims/keytype\": \"PRODUCTION\",\n\"iss\": \"wso2.org/products/am\",\n\"http://wso2.org/claims/applicationname\": \"jwtTest2\",\n\"http://wso2.org/claims/enduserTenantId\": \"0\",\n\"http://wso2.org/claims/applicationUUId\": \"45101ccb-865f-4f48-b7ac-18e43b07edd3\",\n\"client_id\": \"IMJB5ZiR1dHQYBdiMIRAGis1WToa\",\n\"http://wso2.org/claims/subscriber\": \"5f4a7105-a889-4f92-9612-eef5bafe4eec\",\n\"azp\": \"IMJB5ZiR1dHQYBdiMIRAGis1WToa\",\n\"org_id\": \"b554e001-761c-4d3a-a7a6-a61d73d34221\",\n\"http://wso2.org/claims/tier\": \"Unlimited\",\n\"scope\": \"email openid profile\",\n\"exp\": 1690537362,\n\"http://wso2.org/claims/applicationid\": \"45101ccb-865f-4f48-b7ac-18e43b07edd3\",\n\"http://wso2.org/claims/usertype\": \"Application_User\",\n\"org_name\": \"test\",\n\"iat\": 1690533762,\n\"email\": \"testmail@gmail.com\",\n\"jti\": \"69558555-d386-4a81-9ca0-0a23f809cd3c\",\n\"http://wso2.org/claims/apicontext\": \"/b554e001-761c-4d3a-a7a6-a61d73d34221/swog/jwt-test/endpoint-9090-803/1.0.0\"\n}\n

The following table describes the information contained in the sample JWT claims set given above:

Claim Name Description Mandatory/Optional iat The time the token was issued. Mandatory jti The unique token identifier. Mandatory exp The token expiry time. Mandatory iss The issuer of the token. Mandatory http://wso2.org/claims/apiname The name of the API in Choreo. Optional http://wso2.org/claims/version The API version. Optional http://wso2.org/claims/keytype The environment in Choreo that the API is in (Development or production). Optional http://wso2.org/claims/apicontext The API context in Choreo. Optional http://wso2.org/claims/subscriber The subscriber to the API, usually the app developer. Optional http://wso2.org/claims/applicationname The application through which the API invocation is done. Optional http://wso2.org/claims/applicationid The ID of the application through which the API invocation is done. Optional http://wso2.org/claims/applicationUUId The UUID of the application. Optional client_id The client identifier. This is copied from the original token. Optional azp The authorized party (the party to which the ID token was issued). This is copied from the original token. Optional org_id The organization ID. This is copied from the original token. Optional org_name The organization name. This is copied from the original token. Optional http://wso2.org/claims/tier The tier/price band for the subscription. Optional scope The scope of the token. This is copied from the original token. Optional http://wso2.org/claims/usertype The type of application user whose action invoked the API. Optional email The email address of the user. This is copied from the original token. Optional

Note

The claims that get added to the end-user token can vary depending on the grant type used when generating the access token. For example, if you use the client-credentials grant type to generate the access token, the generated backend JWT would contain the following information:

{ \"http://wso2.org/claims/apiname\": \"DefaultAPI\", \"http://wso2.org/claims/version\": \"1.0.0\", \"http://wso2.org/claims/keytype\": \"PRODUCTION\", \"iss\": \"wso2.org/products/am\", \"http://wso2.org/claims/enduserTenantId\": \"0\", \"exp\": 1673245727, \"http://wso2.org/claims/usertype\": \"Application_User\", \"iat\": 1673242127, \"jti\": \"6e3f4392-8bd9-4900-9d08-eaab7429c510\", \"http://wso2.org/claims/apicontext\": \"/9e71ab5e-6df5-4727-92d2-80ecf1a6218d/qbky/default/1.0.0\" }\n

To verify the authenticity of claims in a JWT, the claims must be validated using the public key corresponding to the private key used to sign the JWT.

JSON web key set (JWKS) is a set of keys to validate a JWT. It contains a collection of JSON web keys, which are public keys used to verify the signature of a JWT.

Typically, when a third party (such as an identity provider)issues a JWT and the recipient needs to verify its signature, they can use a JWKS. JWKS allows the issuer to rotate keys dynamically rather than hard-coding the public key in the application. The recipient can obtain the public key by accessing the JWKS endpoint.

"},{"location":"authentication-and-authorization/pass-end-user-attributes-to-upstream-services/#jwks-support-in-choreo-to-validate-the-jwt","title":"JWKS support in Choreo to validate the JWT","text":"

Choreo provides an endpoint to specify the public keys for backend JWT validation. Here are the endpoint URLs for the US East and EU regions:

  • https://gateway.e1-us-east-azure.choreoapis.dev/.wellknown/jwks
  • https://gateway.e1-eu-north-azure.choreoapis.dev/.wellknown/jwks

Note

For private data planes (PDPs), use the following JWKS endpoint URL template:

https://<PDP_GATEWAY_DOMAIN>/.wellknown/jwks

Be sure to replace <PDP-GATEWAY-DOMAIN> with the default domain configured to access the PDP APIs.

The endpoint provides one or more signing keys to validate the JWT. The JSON web keys have a kid identifier that can be matched with the same property on the JWT to decide which key to use when validating.

The following is a sample JWKS response:

{\n\"keys\": [\n{\n\"kty\": \"RSA\",\n\"e\": \"AQAB\",\n\"use\": \"sig\",\n\"kid\": \"ZjcwNmI2ZDJmNWQ0M2I5YzZiYzJmZmM4YjMwMDFlOTA4MGE3ZWZjZTMzNjU3YWU1MzViYjZkOTkzZjYzOGYyNg\",\n\"alg\": \"RS256\",\n\"n\": \"8vjeHzRhvpfMystncPnLBWy_t5F3eCxbcLbdugWnzfnIgaV6TWnqPBUagJBKpzRZs4A9Qja_ZrSVJjYsbARzCS_qiWp0Cdwkqn6ZCXpmbpfjYnKORq8N8M-zWaSZYbNvWJ5oSO4kH-LKWzODaFebwTJBpsR1vChHH95doxFuUjiZaisVaQgUJ6drRdlDtImp9r9EAX36YROuYFPoEJcvsH4_uuAR6ClJ12RE3M-YN4NTi1waVNvGbz43oNrpPy7SXgpizingxSGMqI6WU2ysRmk_f9ALgiPIpFDpufiCTYaIcRT-YcUyp9nMDlTRskMuD-dQ1sdJOa11P_yMs-glfQ\"\n}\n]\n}\n

The following table describes the information contained in the JWKS response:

Property Description kty The cryptographic family to which the key belongs. Choreo only supports RSA. e The exponent value of the public key. use The purpose of the key. For example, whether it is for signing or encryption. kid The identification parameter to match a specific key. alg The algorithm to use with the key. n The modulus value of the public key."},{"location":"authentication-and-authorization/pass-end-user-attributes-to-upstream-services/#enable-passing-end-user-attributes-to-the-backend","title":"Enable passing end-user attributes to the backend","text":"

To enable passing end-user attributes to the backend through API calls via Choreo, follow the steps given below:

  1. Sign in to the Choreo Console.
  2. In the Components Listing\u00a0pane, click on the component for which you want to pass end-user attributes to the backend.
  3. In the left navigation menu, click\u00a0Deploy.

  4. Go to the Set Up card and click Endpoint Configurations. This opens the Endpoint Configurations pane.

    Note

    If the component is an API Proxy, go to the Build Area card and click Security Settings. This opens the Security Settings pane.

  5. Select the\u00a0Pass Security Context To Backend checkbox.

  6. Optionally, specify appropriate audience values in the End User Token Audiences field. Specifying values restricts the JWT to the respective audiences, enabling the backend service to validate and confirm the intended recipients, including itself.

    Note

    The backend JWT does not include the audience field (aud) by default.

  7. Click\u00a0Apply.

  8. To redeploy the component with the applied setting, go to the Set Up card and click Deploy.
"},{"location":"authentication-and-authorization/secure-api-access-with-asgardeo/","title":"Secure API Access with Asgardeo","text":"

API security refers to the measures and practices used to protect Application Programming Interfaces (APIs) from potential threats and vulnerabilities. APIs are essential for enabling communication and data exchange between different software applications and services, making them a critical component in modern software development. However, their openness and accessibility can also make them targets for various security risks. Authentication and authorization are key aspects of API security. Authentication is ensuring that only authorized users or applications can access the API. This can involve using API keys, tokens, or more advanced authentication methods like OAuth 2.0. Authorization is controlling what authenticated users or applications are allowed to do within the API. Authorization mechanisms restrict access to specific resources and actions based on user roles or permissions.

Organizations using Asgardeo for identity and access management (IAM) can seamlessly integrate it with Choreo as an external Identity Provider (IdP). This guide will walk you through setting up Choreo to authenticate API invocations through Asgardeo which is configured as an external IdP.

This guide walks you through the following steps:

  • Assign scopes to an API in Choreo.
  • Create an API in Asgardeo.
  • Create an application in Asgardeo and consume the Asgardeo API.
  • Create an application in Choreo and enable external IdP authentication.
  • Invoke the API with scopes.
"},{"location":"authentication-and-authorization/secure-api-access-with-asgardeo/#prerequisites","title":"Prerequisites","text":"

To follow this guide, you need to satisfy the following prerequisites:

  • Configured Asgardeo as an external IdP
  • If you don't already have a service in Choreo, develop a service or an API Proxy.
  • Deploy and publish your API.
"},{"location":"authentication-and-authorization/secure-api-access-with-asgardeo/#step-1-assign-scopes-to-an-api-in-choreo","title":"Step 1: Assign scopes to an API in Choreo","text":"

You can provide fine-grained access control to your API resources with scopes. Follow the steps below to assign a scope to the resources in the API:

  1. In the Component Listing pane, click on the component you want to attach scopes to.
  2. In the left navigation menu, click Manage and then Permissions.
  3. Click + Add Permission (Scope).
  4. In the Permission List pane, enter the permission value and click + Add New.
  5. Click the copy icon in front of the added scope to copy the fully qualified name of the scope. Save this value for future reference.
  6. To attach a scope to a resource, click the Select Permissions list under the respective resource, and select the scopes you wish to attach.
  7. Click Save and Deploy.
  8. In the left navigation, click Manage and then Lifecycle.
  9. Click Publish and continue to publish your API to the Choreo Developer Portal.
"},{"location":"authentication-and-authorization/secure-api-access-with-asgardeo/#step-2-create-an-api-and-an-application-in-asgardeo","title":"Step 2: Create an API and an application in Asgardeo","text":"

Follow the Asgardeo API Authorization guide to create an application and an API in Asgardeo and to enable API authorization.

Note

  • Use the fully qualified name of the scope when adding scopes.
  • Do the following under the protocol tab:
    • Select JWT as the Access Token.
    • Select the appropriate grant types.
    • Copy the client ID and client secret of the application for future reference.
"},{"location":"authentication-and-authorization/secure-api-access-with-asgardeo/#step-3-create-an-application-in-choreo-and-enable-external-idp-authentication","title":"Step 3: Create an application in Choreo and enable external IdP authentication","text":"

Follow the steps below to consume the Choreo API and use an external IdP for authentication:

  1. Sign in to the Choreo Developer Portal at https://devportal.choreo.dev.
  2. Click Applications. and then click +Create.
  3. Enter a name and description for the application.
  4. Click Create.
  5. In the left navigation, under Credentials and click Production.
  6. Select the Identity Provider as Asgardeo.
  7. Enter the Client ID you copied in step 2.

  8. Click +Add.

    Note

    • You can only use the Client ID in one application.
    • The Identity Provider dropdown is visible only to organizations where you have configured external IdPs.

  9. In the left navigation menu, click Subscriptions.

  10. In the Subscription Management pane that opens, click + Add APIs.
  11. Select the API you assigned scopes to in step 1 and click Add.
"},{"location":"authentication-and-authorization/secure-api-access-with-asgardeo/#step-4-invoke-the-choreo-api-with-scopes","title":"Step 4: Invoke the Choreo API with scopes","text":"
  1. On the Choreo Developer Portal, go to your application.
  2. In the left navigation menu, under Credentials and click Production.
  3. Under Endpoints, copy the Token Endpoint URL.

  4. Obtain an access token by invoking the token endpoint as follows:

    Note

    • If you are using the production credentials, you need to deploy your component(endpoint) to the production environment by promoting it from the development environment.
    • If you are using the sandbox credentials, you can use the endpoints deployed in the development environment.
    FormatExample 
    curl -X POST '<TOKEN_ENDPOINT>?grant_type=password&scope=<REQUIRED_SCOPES>&username=<USER_NAME>&password=<USER_PASSWORD>' \\\n--header 'Content-Type: application/x-www-form-urlencoded' \\\n--header 'Authorization: Basic <BASE64-ENCODED ASGARDEO_APP_CLIENT_ID:ASGARDEO_APP_CLIENT_SECRET>'\n
    curl -X POST 'https://dev.api.asgardeo.io/t/orgHandle/oauth2/token?grant_type=password&scope=<REQUIRED_SCOPES>&username=<USER_NAME>&password=<USER_PASSWORD>' \\\n--header 'Content-Type: application/x-www-form-urlencoded' \\\n--header 'Authorization: Basic <BASE64-ENCODED CLIENT_ID:CLIENT_SECRET>'\n

  5. Once you receive the access token, you can test invoking the resource using the OpenAPI console in Choreo by specifying the scope.

"},{"location":"authentication-and-authorization/secure-api-access-with-azure-ad/","title":"Secure API Access with Microsoft Azure Active Directory (Azure AD)","text":"

API security refers to the measures and practices used to protect Application Programming Interfaces (APIs) from potential threats and vulnerabilities. Authentication and authorization are key aspects of API security. Authentication is ensuring that only authorized users or applications can access the API. This can involve using API keys, tokens, or more advanced authentication methods like OAuth 2.0. Authorization is controlling what authenticated users or applications are allowed to do within the API. Authorization mechanisms restrict access to specific resources and actions based on user roles or permissions.

Organizations using Microsoft Azure AD for identity and access management (IAM) can seamlessly integrate it with Choreo as an external Identity Provider (IdP). This guide will walk you through setting up Choreo to authenticate API invocations through Azure AD which is configured as an external IdP.

This guide walks you through the following steps:

  • Assign scopes to an API in Choreo.
  • Create an API in Azure AD.
  • Create an application in Azure AD and consume the Azure API.
  • Create an application in Choreo and enable external IdP authentication.
  • Invoke the API with scopes.
"},{"location":"authentication-and-authorization/secure-api-access-with-azure-ad/#prerequisites","title":"Prerequisites","text":"

To follow this guide, you need to satisfy the following prerequisites:

  • Configure Azure AD as an external IdP.
  • An API: If you don't already have a service in Choreo, develop a service or an API Proxy.
  • Deploy and publish your API.
  • An Azure Active Directory account: If you don\u2019t already have one, set up an Azure Active Directory account at https://azure.microsoft.com/en-gb/.
  • Administrator rights to your Choreo organization: You need this to configure the Azure AD account in your organization.
  • To create applications, the Application Developer role is required. Learn more
"},{"location":"authentication-and-authorization/secure-api-access-with-azure-ad/#step-1-assign-scopes-to-an-api-in-choreo","title":"Step 1: Assign scopes to an API in Choreo","text":"

You can provide fine-grained access control to your API resources with scopes. Follow the steps below to assign a scope to the resources in the API:

  1. In the Component Listing pane, click on the component you want to attach scopes to.
  2. In the left navigation menu, click Manage and then Permissions.
  3. Click + Add Permission (Scope).
  4. In the Permission List pane, enter the permission value and click + Add New.
  5. Click the copy icon in front of the added scope to copy the fully qualified name of the scope. Save this value for future reference.
  6. To attach a scope to a resource, click the Select Permissions list under the respective resource, and select the scopes you wish to attach.
  7. Click Save and Deploy.
  8. In the left navigation menu, click Manage and then Lifecycle.
  9. Click Publish and continue to publish your API to the Choreo Developer Portal.
"},{"location":"authentication-and-authorization/secure-api-access-with-azure-ad/#step-2-create-a-web-api-on-azure-ad","title":"Step 2: Create a web API on Azure AD","text":"

To enable external IdP authentication for APIs, create an API on Azure AD that represents the API on Choreo. Follow the steps below:

  1. Sign in to the Azure console.
  2. Follow the Azure guide to create a Web API that represents your API on Choreo.
  3. In the left navigation menu, under Manage, select Expose an API.
  4. Add the default Application ID URI and click Save and Continue.
  5. Under Scopes defined by this API, select Add a scope.
  6. Enter the fully qualified name as the scope name.
  7. Define who can consent. You can alternatively add a scope requiring admin consent.
  8. Enter appropriate values and click Add Scope.

For more information, refer to the Azure documentation:

  • Quickstart: Register an application with the Microsoft identity platform
  • Quickstart: Configure an application to expose a web API
"},{"location":"authentication-and-authorization/secure-api-access-with-azure-ad/#step-21-assign-users-to-the-web-api","title":"Step 2.1: Assign users to the web API","text":"

You can restrict users to the API as follows:

  1. Go to your Azure AD main menu.
  2. Under Manage, click on Enterprise Applications. Alternatively, on Microsoft Entra, under Applications, click Enterprise Applications.
  3. Select your API.
  4. Under Manage, select the Users and groups then select + Add user/group.
  5. Select the users and groups and click Select.

For more information, refer to the Azure documentation: Assign the app to users and groups to restrict access

"},{"location":"authentication-and-authorization/secure-api-access-with-azure-ad/#step-3-create-a-client-application-on-azure-ad-and-invoke-the-azure-web-api","title":"Step 3: Create a client application on Azure AD and invoke the Azure web API","text":"

To expose the API to application developers, create an application in Azure AD. This application provides you with a client-id and client-secret that your application needs to use to invoke the API.

"},{"location":"authentication-and-authorization/secure-api-access-with-azure-ad/#step-31-create-a-client-application","title":"Step 3.1: Create a client application","text":"

Follow the steps below to create the application:

  1. Follow the steps in Register an application on Azure to create an application.

  2. Configure the platform settings. Enter your client application's redirect URI in the process.

    Note

    OAuth2 Authorization Grant flow applies to Web Applications.

"},{"location":"authentication-and-authorization/secure-api-access-with-azure-ad/#step-32-consume-the-azure-ad-web-api-from-the-azure-ad-application","title":"Step 3.2: Consume the Azure AD web API from the Azure AD application","text":"

Once you create the application, select the API and the scopes you want the application to consume. Follow the steps below:

  1. Go to Azure Active Directory and then click App registrations.
  2. Select your client application (not your web API).
  3. In the left navigation menu, click API permissions.
  4. Click + Add a permission and select My APIs.
  5. Select the API and the required scopes and click Add Permissions.
  6. Once you add the scope, click on the scope and copy the scope name and keep it for future reference. Use this as the scope when you invoke the authorize and token endpoint in step 5.

For more information, refer to the Azure documentation: Add permissions to access your web API

"},{"location":"authentication-and-authorization/secure-api-access-with-azure-ad/#step-33-create-secrets-for-the-azure-web-application","title":"Step 3.3: Create secrets for the Azure web application","text":"

To invoke the application, provide client secrets to the consuming application. Follow the steps below to generate the credentials:

  1. In the left navigation menu, click Certificates & Secrets.
  2. Click + New client secret.
  3. Provide a meaningful description and the required expiration.
  4. Click Add.
  5. Copy the created Secret ID and Value for future reference.
  6. In the left navigation menu, click Overview and open the overview page of the API.
  7. Copy the Application (client) ID and save it for future reference.

For more information, refer to the Azure documentation: Add a Client Secret

"},{"location":"authentication-and-authorization/secure-api-access-with-azure-ad/#step-4-create-an-application-in-choreo-and-enable-external-idp-authentication","title":"Step 4: Create an application in Choreo and enable external IdP authentication.","text":"

Follow the steps below to consume the Choreo API and use an external IdP for authentication:

  1. Sign in to the Choreo Developer Portal at https://devportal.choreo.dev.
  2. Click Applications. and then click +Create.
  3. Enter a name and description for the application.
  4. Click Create.
  5. In the left navigation menu, under Credentials and click Production.
  6. Select your AzureAD (Microsoft) configuration as the Identity Provider.
  7. Enter the Application (client) ID you copied in at Step 3.2 as the Client ID.

  8. Click +Add.

    Note

    • You can only use the Client ID in one application.
    • The Identity Provider dropdown is visible only to organizations where you have configured external IdPs.

  9. In the left navigation menu, click Subscriptions.

  10. In the Subscription Management pane that opens, click + Add APIs.
  11. Select the API you assigned scopes to in step 1 and click Add.
"},{"location":"authentication-and-authorization/secure-api-access-with-azure-ad/#step-5-invoke-the-api-with-scopes","title":"Step 5: Invoke the API with scopes","text":"

You can now invoke the Choreo API using the authorization code grant. Choreo will authenticate the user with Azure AD and provide access to the resource.

  1. On the Choreo Developer Portal, go to your application.
  2. In the left navigation menu, under Credentials and click Production.
  3. Under Endpoints, copy the Authorize Endpoint URL.

  4. Invoke the authorization endpoint as follows:

    FormatExample 
    {authorize_url}?client_id={client_id}&redirect_uri={redirect_url}&scope={scopes}&response_mode=query&response_type=code\n
    https://login.microsoftonline.com/dd912d48-b0be-401f-b18c-8ca89e9c0b6c/oauth2/authorize?client_id=5eb1de74-e449-4973-a620-52c4dc9157a9&redirect_uri=https://localhost:9000&scope=api://580b40b7-5513-4714-a4e0-8d4e784f7dc6/urn:taylordean:books:books_addt&response_mode=query&response_type=code\n
    1. Review the consent in the login screens that prompt and continue.
    2. After you log in, you will receive an authorization code in the URL. Copy the authorization code and use it to get an access token from Azure AD by following the next steps.
    3. On the Choreo Developer Portal, go to your application.
    4. In the left navigation menu, under Credentials and click Production.
    5. Under Endpoints, copy the Token Endpoint URL.
    6. Invoke the token endpoint as follows:
    FormatExample 
    curl -X POST -H 'Content-Type: application/x-www-form-urlencoded' \\\n{token_endpoint} \\\n-d 'client_id={client_id}' \\\n-d 'scope={scopes}' \\\n-d 'code={authorization_code}' \\\n-d 'redirect_uri={redirect_url}' \\\n-d 'client_secret={The client_secret value you copied from the Azure Application}'\n-d 'grant_type=authorization_code' \\    \n
    curl -X POST -H 'Content-Type: application/x-www-form-urlencoded' \\\nhttps://login.microsoftonline.com/dd912d48-b0be-401f-b18c-8ca89e9c0b6c/oauth2/v2.0/token \\\n-d 'client_id=5eb1de74-e449-4973-a620-52c4dc9157a9' \\\n-d 'scope=api://580b40b7-5513-4714-a4e0-8d4e784f7dc6/urn:taylordean:books:books_add' \\\n-d 'code=0.AXAASC\u2026zZUzKYm18yM_5-SXz1uvRbbGYF7F32hE9zIQFRQY35haD' \\\n-d 'redirect_uri=https://localhost:9000' \\\n-d 'grant_type=authorization_code' \\\n-d 'state=111' \\\n-d 'client_secret=l4Q8Q~4WKiRXYSQZly5E6Ess.fKf__U1yJR3IaMd'\n

  5. Once you receive the access token, you can test invoking the resource using the OpenAPI console in Choreo by specifying the scope.

"},{"location":"authentication-and-authorization/secure-communication-between-the-choreo-gateway-and-your-backend-with-mutual-tls/","title":"Secure Communication Between the Choreo Gateway and Your Backend with Mutual TLS","text":"

To establish secure communication between the Choreo Gateway and your backend, you can configure mutual TLS.

Mutual TLS authentication involves both the client and server validating each other\u2019s certificates before establishing a connection. The following diagram depicts this scenario:

"},{"location":"authentication-and-authorization/secure-communication-between-the-choreo-gateway-and-your-backend-with-mutual-tls/#configure-mutual-tls-to-establish-secure-connectivity","title":"Configure mutual TLS to establish secure connectivity","text":"

To establish secure connectivity between the Choreo Gateway and your backend using mutual TLS, you must add the certificate of the backend (server certificate) to Choreo and add the certificate of Choreo (client certificate) as a trusted certificate in the backend.

"},{"location":"authentication-and-authorization/secure-communication-between-the-choreo-gateway-and-your-backend-with-mutual-tls/#step-1-configure-the-backend-certificate","title":"Step 1: Configure the backend certificate","text":"Prerequisites
  • The endpoint must be protected with TLS.
  • The public certificate of the backend server should be extracted in PEM format and saved on the disk with the .pem extension.

To configure the backend certificate, follow the steps given below:

  1. Sign in to the Choreo Console.
  2. In the Component Listing pane, click on the API proxy for which you want to configure TLS. For instructions on how to create an API proxy component, see Develop an API Proxy: Step 1.
  3. In the left navigation menu, click Develop and then click Endpoints.
  4. On the Endpoints page, click Configure corresponding to the endpoint.
  5. Click Upload Endpoint Certificate, and select the certificate file that you extracted in the prerequisites section to add it. This adds the certificate to all the environments as the default certificate for the endpoint. You can override this certificate if necessary when you deploy or promote the API.
"},{"location":"authentication-and-authorization/secure-communication-between-the-choreo-gateway-and-your-backend-with-mutual-tls/#step-2-configure-mutual-tls-with-the-backend-service","title":"Step 2: Configure mutual TLS with the backend service","text":"

There are two approaches you can take to configure mutual TLS.

  • Generate a key pair with a self-signed certificate from Choreo, download the public certificate, and subsequently add and configure it in the backend.
  • Upload your own public or private certificate pair to Choreo. Subsequently, add and configure the public certificate of this key pair in your backend.

Follow the step-by-step instructions below depending on how you want to establish mutual TLS with the backend service:

Generate a key pair through ChoreoUse your own certificate pair

When you follow these steps, Choreo generates a key pair with a self-signed certificate. You can attach this key pair to any API proxy created within the same project.

  1. Sign in to the Choreo Console.
  2. In the Component Listing pane, click on the API proxy for which you want to generate a key pair. For instructions on how to create an API proxy component, see Develop an API Proxy: Step 1.
  3. In the left navigation menu, click Develop and then click Endpoints.
  4. On the Endpoints page, click Configure corresponding to the endpoint.
  5. If your backend does not use a CA-signed certificate and you have not already added the backend certificate, click Upload Endpoint Certificate and add the backend certificate.
  6. To enable mutual SSL, turn on the Mutual SSL toggle.
  7. Click Add Client Certificate.

  8. In the Add Client Certificate Pair dialog, select Generate new key pair and specify a value as the common name for the certificate pair. This value will be used to identify the certificate.

  9. Optionally, click Show advanced options to expand the section and specify appropriate values for each of the fields.

  10. Click Generate. This generates the certificate and lists it under Existing Certificates.

  11. Click the more options icon corresponding to the certificate and then click View and Download.

    This opens the certificate for you to view and download.

  12. To download the certificate in PEM format, click Download. You can add this certificate as a trusted certificate in the API backend server.

Now you can associate the certificate with the API and deploy the API.

Here, you can use your own public certificate and private certificate as client certificates.

  1. Sign in to the Choreo Console.
  2. In the Component Listing pane, click on the API proxy for which you want to generate a key pair. For instructions on how to create an API proxy component, see Develop an API Proxy: Step 1.
  3. In the left navigation menu, click Develop and then click Endpoints.
  4. On the Endpoints page, click Configure corresponding to the endpoint.
  5. If your backend does not use a CA-signed certificate and you have not already added the backend certificate, click Upload Endpoint Certificate and add the backend certificate.
  6. To enable mutual SSL, turn on the Mutual SSL toggle.
  7. Click Add Client Certificate.

  8. In the Add Client Certificate Pair dialog, select Use my own key pair.

  9. Upload the private key and public certificate in PEM format or copy and paste the content of the private key and public certificate.

  10. Click Add. This generates the certificate and lists it under Existing Certificates.

  11. Click the more options icon corresponding to the certificate and then click View and Download.

    This opens the certificate for you to view and download.

  12. To download the certificate in PEM format, click Download. You can add this certificate as a trusted certificate in the API backend server.

Now you can associate the certificate with the API and deploy the API.

"},{"location":"authentication-and-authorization/secure-communication-between-the-choreo-gateway-and-your-backend-with-mutual-tls/#step-3-associate-the-certificate-with-the-api","title":"Step 3: Associate the certificate with the API","text":"

To associate a certificate with the API, follow the steps given below:

  1. On the Endpoints page, go to the Existing Certificates section.

  2. Select the certificate you want to associate with the API.

  3. Click Save.

"},{"location":"authentication-and-authorization/secure-communication-between-the-choreo-gateway-and-your-backend-with-mutual-tls/#step-4-deploy-the-api","title":"Step 4: Deploy the API","text":"

To deploy the API, follow the steps given below:

  1. In the left navigation menu, click Deploy.
  2. In the Build Area card, click Configure & Deploy.
  3. Once the mediation application generation phase is complete, verify the endpoint URL populated for the environment and then click Save & Deploy.

Once the deployment is complete, you can test the API.

"},{"location":"authentication-and-authorization/secure-communication-between-the-choreo-gateway-and-your-backend-with-mutual-tls/#change-the-certificate-for-the-production-environment","title":"Change the certificate for the production environment","text":"

If the API backend changes depending on the environment, the respective certificate must be updated for each environment.

Here, let's take a look at the steps to update the certificate for the production environment:

  1. On the Deploy page, go to the Development card and click Promote.
  2. In the Configurations pane that opens, click Endpoint Configuration. You will see all applicable certificates listed in the Mutual TLS list.
  3. Select the certificate applicable to the production environment and click Promote. This promotes the component to the production environment with the selected certificate.
"},{"location":"authentication-and-authorization/secure-web-applications-with-managed-authentication/","title":"Secure Web Applications with Managed Authentication","text":"

The managed authentication capability of Choreo simplifies adding authentication and authorization to a single-page web application.

As a developer, you can easily set up Choreo's managed authentication to seamlessly integrate authentication into your web application. You just need to enable Choreo\u2019s managed authentication, configure the built-in identity provider, and connect to Choreo without having to deal with the complexities of underlying OIDC/OAuth2.0 protocols.

Choreo's managed authentication follows the backend for frontend (BFF) architecture, which is a secure pattern recommended for browser-based applications that utilize OIDC/OAuth2.0 for authentication and authorization. This architecture ensures that OAuth tokens remain secure from browser-side code, making them immune to potential attacks like cross-site scripting (XSS).

Note

Choreo's managed authentication is currently available only for web applications created with React, Angular, or Vue.js buildpacks.

Warning

Managed authentication uses the 'SAMESITE' cookie attribute to prevent CSRF attacks. Therefore, it is recommended to use managed authentication with modern browsers that support the 'SAMESITE' attribute.

"},{"location":"authentication-and-authorization/secure-web-applications-with-managed-authentication/#step-1-set-up-managed-authentication-for-your-web-application","title":"Step 1: Set up managed authentication for your web application","text":"

To secure your web application, you must implement authentication and authorization for it.

To easily set up authentication for your web application with Choreo's managed authentication, follow the steps given below. Before you move on to the next section, see Develop Web Applications Locally with Choreo\u2019s Managed Authentication to ensure a seamless authentication experience when developing your web application on your local machine. You can also refer to the sample\u00a0React app with managed authentication.

"},{"location":"authentication-and-authorization/secure-web-applications-with-managed-authentication/#step-11-implement-the-sign-in-functionality","title":"Step 1.1: Implement the sign-in functionality","text":"

To allow Choreo to manage the sign-in functionality for your web application, you must implement a sign-in button that redirects users to the /auth/login path on click. You can use the following code snippet or any custom button component from a preferred UI component library:

<button onClick={() => {window.location.href=\"/auth/login\"}}>Login</button>\n

This code snippet works as follows:

When a user clicks sign in on your web application, Choreo will redirect the user to the configured identity provider and handle the authentication process, conforming to the OICD/OAuth2.0 protocols. On successful sign-in, Choreo will set the relevant session cookies and redirect the user to the post-sign-in path (default is /). The user can then invoke any Choreo-deployed APIs depending on the permission granted.

Note

Refer to configure the identity provider section for details on configuring an identity provider for the web application.

Optional: Pass additional query parameters to the identity provider

If you want to pass additional query parameters to the identity provider, include them in the /auth/login request. Choreo appends these parameters to the authorize request sent to the identity provider.

For example,

<button onClick={() => {window.location.href=\"/auth/login?fidp=myfederatedidp\"}}>Login</button>\n
"},{"location":"authentication-and-authorization/secure-web-applications-with-managed-authentication/#step-12-obtain-user-information-claims","title":"Step 1.2: Obtain user information claims","text":"

Choreo's managed authentication allows you to access user information claims that the identity provider returns post-sign-in, either via a cookie or by invoking a GET resource.

Obtain user information via the userinfo cookie

Upon successful sign-in, Choreo's managed authentication establishes a userinfo cookie that is accessible from the post-sign-in path you configured (by default, set to /). This userinfo cookie, provided by the identity provider, contains encoded user information claims.

Note

  • The userinfo cookie is intentionally set to have a short lifespan of only 2 minutes.
  • As a developer, you can decide how to utilize the user information that you retrieve. You must securely store the user information because the stored information can also serve as a means to verify the logged-in state of a user.
  • The following example uses the js-cookie library for cookie parsing. You can use any cookie-parsing library of your choice.\u00a0

The recommended approach is to retrieve user information from the cookie and subsequently clear the cookie. The following is a sample code snippet that you can include in your post-sign-in path to retrieve user information from the cookie and subsequently clear the cookie:

    import Cookies from 'js-cookie';\n// Read userinfo cookie value.\nconst encodedUserInfo = Cookies.get('userinfo')\n// Decode the value. \nconst userInfo = JSON.parse(atob(encodedUserInfo))\n// Store the value in a preferred browser-based storage if needed.\n// Clear the cookie.\nCookies.remove('userinfo', { path: <post-login-path> })\n
Obtain user information via a GET endpoint

Choreo's managed authentication provides the GET endpoint /auth/userinfo in addition to the userinfo cookie that it sets after successful sign-in. You can use this endpoint to query information about users who have signed in. It also serves as a mechanism to check the state of a user who has signed in.

The following is an example of a request to this endpoint:

const response = await fetch('/auth/userinfo')\n

If a user has signed in, the server sends a 200 OK response with the user information in JSON format in the response body. However, if the user is not signed in, the server sends a 401 Unauthorized response.

"},{"location":"authentication-and-authorization/secure-web-applications-with-managed-authentication/#step-13-implement-the-sign-out-functionality","title":"Step 1.3: Implement the sign-out functionality","text":"

To allow Choreo to manage the sign-out functionality of your web application, you can implement a sign-out button to redirect users to the /auth/logout path along with the session_hint cookie value on click. You can use the following code snippet or any custom button component from a preferred UI component library:

Note

  • It is recommended to clear any user information (if stored) at the time of sign-out.
  • The following example uses the js-cookie library for cookie parsing. You can use any cookie-parsing library of your choice.\u00a0 
<button onClick={async () => {\nwindow.location.href = `/auth/logout?session_hint=${Cookies.get('session_hint')}`;\n}}>Logout</button>`\n

When a user clicks the sign-out button, Choreo will clear the session cookies and redirect the users to the OIDC logout endpoint of the configured identity provider (if available).\u00a0\u00a0

"},{"location":"authentication-and-authorization/secure-web-applications-with-managed-authentication/#step-14-invoke-apis","title":"Step 1.4: Invoke APIs","text":"

To invoke Choreo APIs within the same organization as your web application, you can use the relative path /choreo-apis/<api-suffix>, regardless of whether managed authentication is enabled for the web application or not.

Note

To invoke a Choreo API from a web application, you need to create a Connection from the web application to the Choreo API.

For example, if the API URL is https://2d9ec1f6-2f04-4127-974f-0a3b20e97af5-dev.e1-us-east-azure.choreoapis.dev/rbln/item-service/api-e04/1.0.0, the <api-suffix> would be /rbln/item-service/api-e04/1.0.0. You can invoke the API using the /choreo-apis/rbln/item-service/api-e04/1.0.0 relative path from your single-page application.

Info

To copy the exact service URL of a Connection, you can follow the steps given below: 1. In the Choreo Console, go to the appropriate web application component. 2. In the left navigation menu, click Connections under Dependencies. 3. Click on the required Connection and copy the service URL.

If you enable Choreo's managed authentication, you don't have to manually add any logic to attach an access token to the API call because Choreo APIs accept the cookies set by Choreo's managed authentication. You can directly invoke the API as follows:

    const response = await fetch('/choreo-apis/<api-suffix>')\n

If Choreo's managed authentication is disabled, you must ensure that your web application attaches a valid access token to the API call.

"},{"location":"authentication-and-authorization/secure-web-applications-with-managed-authentication/#step-15-handle-session-expiry","title":"Step 1.5: Handle session expiry","text":"

When a user session exceeds the configured session expiry time, it automatically expires. A 401 Unauthorized response status code for a Choreo API request from a logged-in user indicates that the session may have expired, requiring the user to re-login.

To programmatically handle session expiry and automatically re-login upon receiving a 401 Unauthorized response from a Choreo API, you can encapsulate the request with re-login logic. The following sample code snippet shows how to wrap GET requests:

    export const performGet = async (url) => {\ntry {\n// API call\nreturn await fetch('/choreo-apis/<api-suffix>');\n} catch (error) {\nif (error instanceof HttpError && error.status === 401) {\n// Re-login\nwindow.location.href = \"/auth/login\";\n} else {\nthrow error;\n}\n}\n};\n
"},{"location":"authentication-and-authorization/secure-web-applications-with-managed-authentication/#step-16-set-up-a-custom-error-page","title":"Step 1.6: Set up a custom error page","text":"

You can set up Choreo's managed authentication to redirect to a customized error page within your web application by defining the error path in the configuration. In the event of an error during a redirection-based process, such as sign in or sign out, Choreo will automatically redirect the user to the designated custom error page.

Note

If you have not configured an error path, Choreo's managed authentication will use its default error page whenever an error occurs.

Choreo's managed authentication will include the following query parameters in the URL when redirecting to the custom error page:

Parameter Description code A short textual error code indicating the error message The description of the error

Now have successfully implemented Choreo's managed authentication for your web application. The next step is to enable managed authentication for the component, and subsequently deploy it.

"},{"location":"authentication-and-authorization/secure-web-applications-with-managed-authentication/#step-2-enable-managed-authentication-and-configure-the-paths","title":"Step 2: Enable managed authentication and configure the paths","text":"

To ensure that your web application functions seamlessly with managed authentication, it is essential to enable managed authentication for your web application component within Choreo.

You can enable managed authentication for your web application component at the time you deploy the component.

Tip

Managed authentication is enabled by default when you create a web application using React, Angular, or Vue.js buildpacks.

  1. Sign in to the Choreo Console. This opens the project home page.
  2. In the Component Listing pane, click on the web application for which you want to enable managed authentication.
  3. In the left navigation menu, click Deploy.
  4. In the Set Up card, click Configure & Deploy.
  5. Add the necessary configurations for your component if applicable and click Next.
  6. Make sure Managed Authentication with Choreo toggle is enabled.

  7. Specify appropriate values for the following fields:

    Field Description Default value Post Login Path The relative path that the application will be redirected to on successful sign-in. In your code, you must implement the necessary logic to obtain signed-in user's information from the userinfo cookie set by managed authentication. See Obtain user information via the userinfo cookie section in Obtain user information claims. / Post Logout Path The relative path to which Choreo redirects you on successful sign-out. / Error Path The relative path to which Choreo redirects you when an error occurs during a redirection-based flow (i.e., sign in or sign out). See Set up a custom error page. Built-in error page Session Expiry Time The time in minutes after which the user session expires. For a seamless experience, the session expiry value should match the refresh token expiry time of the OIDC application in your identity provider. 10080 Minutes (7 Days) Additional Scopes All additional scopes required by the web application. The openid, profile, and email scopes are added by default together with the scopes required to invoke subscribed APIs. none

    Note

    If you need to change these configurations after you deploy the component, you can click Authentication Settings on the Set Up card, make the necessary changes, and deploy the component once again.

"},{"location":"authentication-and-authorization/secure-web-applications-with-managed-authentication/#step-3-configure-the-identity-provider-for-the-web-application","title":"Step 3: Configure the identity provider for the web application","text":"

You can configure your web application to work with the Choreo built-in identity provider, Asgardeo, or any external identity provider which supports OIDC/OAuth2.0 .

Note

The identity provider configured in this step should contain the users for the web application.

Click the respective tab for details depending on which identity provider you need to configure:

Configure Choreo built-in identity providerConfigure AsgardeoConfigure an external identity provider

Follow the steps given below to configure the built-in identity provider by generating authentication keys:

Note

Choreo built-in identity provider is configured by default. Therefore, this step is optional.

  1. In the Choreo Console, go to the component for which you want to manage OAuth keys.
  2. In the left navigation menu, click Settings.
  3. Click the Authentication Keys tab and then click on the environment for which you want to generate keys.
  4. In the Identity Provider list, select Choreo Built-In Identity Provider.

  5. Click Generate Secret.

    Note

    If the Regenerate Secret button is shown instead of the Generate Secret button, it indicates that OAuth keys are already generated for the component for the selected environment.

Tip

Refer to Configure a User Store with the Built-In Identity Provider for details on adding test users in Choreo built-in identity provider.

Tip

If you need to invoke APIs secured with role-based access control, you can test this within Choreo by creating roles for the application and mapping those roles to relevant permissions (scope) and user groups. For more information, see create roles and assign permissions and assign roles to user groups sections in Test Secure API Access with Choreo Built-In Security Token Service.

Step 3.1: Create and configure an OIDC/OAuth2.0 application in Asgardeo

  1. Sign in to Asgardeo.
  2. In the top navigation menu, click the Organization list and select your organization.
  3. In the Asgardeo Console left navigation menu, click Applications.
  4. Click + New Application.
  5. Click Standard-Based Application.
  6. Specify a name for the application and select OAuth2.0 OpenID Connect as the protocol.
  7. Click Register.

  8. Click the Protocol tab and follow these steps:

    1. Select Code and Refresh Token as the Allowed grant types.
    2. Specify the following as Authorized redirect URLs:
      • [your-web-application-url]/auth/login/callback
      • [your-web-application-url]/auth/logout/callback
    3. Specify your web application URL under Allowed origins.
    4. In the Access Token section, select JWT as the Token type.

    5. Click Update.

      Tip

      If you need to invoke APIs secured with role-based access control, you must create roles in the application and map those roles to relevant permissions (scope). Then those roles should be assigned to user groups. For more information, see the Asgardeo API authorization guide.

    6. Copy the Client ID and Client Secret of the application. You will need to use these values in the next step to link the OIDC/OAuth2.0 application to your Choreo component.

Step 3.2: Link the OIDC/OAuth2.0 application to the Choreo web application component

  1. In the Choreo Console, go to the component for which you want to manage OAuth keys.
  2. In the left navigation menu, click Settings.
  3. Click the Authentication Keys tab and then click on the environment for which you want to generate keys.
  4. In the Identity Provider list, select Asgardeo - [your-org-name].
  5. Paste the Client ID and Client Secret of the OIDC/OAuth2.0 application you created in Asgardeo.
  6. Click Add Keys.

Step 3.1: Create and configure an OIDC/OAuth2.0 application in the external identity provider

  1. Create an OIDC/OAuth2.0 application in your external identity provider.

  2. Configure the OIDC/OAuth2.0 application as follows:

    1. Set Code and Refresh Token as allowed grant types.
    2. Add the following as authorized redirect URL.
    3. Specify the following as authorized redirect URLs:

    4. Specify the access token type as JWT.

      Tip

      If you want to invoke APIs secured with role-based access control, you must ensure that users are assigned a role mapping that grants the necessary permission for API invocation. The approach of mapping application roles to users can vary depending on the identity provider.

Step 3.2: Link the OIDC/OAuth2.0 application to the Choreo component

  1. In the Choreo Console, go to the component for which you want to manage OAuth keys.
  2. In the left navigation menu, click Settings.
  3. Click the Authentication Keys tab and then click on the environment for which you want to generate keys.
  4. In the Identity Provider list, select your identity provider.
  5. Paste the Client ID and Client Secret of the OIDC/OAuth2.0 application you created in your external identity provider.
  6. Click Add Keys.
"},{"location":"authentication-and-authorization/test-secure-api-access-with-choreo-built-in-security-token-service/","title":"Test Secure API Access with Choreo Built-In Security Token Service","text":"

API security can protect APIs from potential threats and vulnerabilities, with authentication and authorization playing key roles. Authentication ensures that only authorized users or applications can access the API. This involves using API keys, tokens, or more advanced authentication methods like OAuth 2.0. Authorization governs the actions permitted for authenticated users or applications within the API. Authorization mechanisms restrict access to specific resources and actions based on user roles or permissions.

Choreo simplifies security testing for developers, allowing them to easily test APIs with permissions in non-critical environments. With its integrated security token service, Choreo provides authorization features that generate scopes based on the correlation between scopes, roles, and user groups. Developers can create roles, assign permissions, and set up user-group mappings using Choreo's built-in identity provider (IdP).

This guide walks you through the following steps to test the invocation of secured APIs with permissions using Choreo's built-in authorization capability:

  • Assign scopes to an API in Choreo.
  • Create roles and assign permissions in Choreo.
  • Assign roles to user groups.
  • Test the API invocation.
    • When Choreo manages the authentication (i.e., managed authentication enabled).
    • When the application independently handles the authentication (i.e., managed authentication disabled).
"},{"location":"authentication-and-authorization/test-secure-api-access-with-choreo-built-in-security-token-service/#prerequisites","title":"Prerequisites","text":"

Before you try out this guide, ensure you have set up the following:

  • Configure the Choreo built-in identity provider with users. For step-by-step instructions, see Configure a User Store with the Built-In Identity Provider.
  • Deploy and publish an API via Choreo. If you don't have an existing service in Choreo, you can either develop a service or an API Proxy.
  • A web application for API subscription. If you don't have an application in Choreo, you must create a web application
  • Administrator rights in your Choreo organization. You need this access to configure role-group and role-permission mappings.
"},{"location":"authentication-and-authorization/test-secure-api-access-with-choreo-built-in-security-token-service/#step-1-assign-permissions-to-an-api-in-choreo","title":"Step 1: Assign permissions to an API in Choreo","text":"

You can provide fine-grained access control to your API resources with permissions. Follow the steps below to assign permissions to the resources in the API:

  1. Go to https://console.choreo.dev/ and sign in.
  2. In the Choreo Console top navigation menu, click the Project list and select the project that contains your component.
  3. In the Component Listing pane, click on the component for which you want to attach permissions.
  4. In the left navigation menu, click Deploy.
  5. On the Deploy page, go to the Set Up card and click Endpoint Configurations. This opens the Endpoint Configurations pane.
  6. Go to the Permissions List section and click + Add Permission(Scope).
  7. In the Permissions List section, enter a permission value and click + Add New.
  8. Click the copy icon in front of the added permission to copy the fully qualified name of it. Save this value for future reference.
  9. To attach permissions to a resource, click the Select Permissions list under the respective resource and select the permissions you want to attach.
  10. Click Apply.

  11. To apply the latest permissions to the deployed component, you must redeploy it. Follow the steps below to redeploy:

    1. Go to the Set Up card and click Configure & Deploy.
    2. In the Configurations pane that opens, click Next. This opens the Endpoint Details pane.
    3. Click Deploy.

  12. To publish your API to the Choreo Developer Portal, follow the steps given below:

    1. In the left navigation menu, click Manage and then click Lifecycle.
    2. Click Publish.
"},{"location":"authentication-and-authorization/test-secure-api-access-with-choreo-built-in-security-token-service/#step-2-create-roles-and-assign-permissions","title":"Step 2: Create roles and assign permissions","text":"

The permissions assigned to your API need to be associated with roles. Follow the steps below to create roles and assign permissions to the roles.

  1. In the Choreo Console, go to the top navigation menu, click the Project list, and select the project that contains your component.
  2. In the left navigation menu, click Settings.
  3. Click the Application Security tab.
  4. Click + Role.
  5. Specify an appropriate Role Name and Role description.

  6. Select the permissions you want to assign to the role, and then click Create.

    Tip

    The permissions(scopes) defined for APIs exposed via components in the project and the permissions(scopes) required by connections created for components in the project are listed here.

"},{"location":"authentication-and-authorization/test-secure-api-access-with-choreo-built-in-security-token-service/#step-3-assign-roles-to-user-groups","title":"Step 3: Assign roles to user groups","text":"

You must assign roles to the user groups defined in your Choreo built-in IdP to ensure that authenticated users can obtain access tokens with the required permissions.

  1. In the Choreo Console, go to the top navigation menu, click the Organization list, and select the organization where you created your component.

  2. Click the Application Security tab and then click Role Management.

    Tip

    The roles defined within different projects in the organization are listed here.

  3. Click Map Groups corresponding to a role that you want to assign to a group.

  4. Specify a group name and enter to add it. You can add multiple groups if necessary.
  5. Click Save.
"},{"location":"authentication-and-authorization/test-secure-api-access-with-choreo-built-in-security-token-service/#step-4-test-the-api-invocation","title":"Step 4: Test the API invocation","text":"

To test an API invocation, you must first create a connection to your API. To do this, you must have a web application created. You can use the web application you created while setting up the prerequisites.

To create a connection to the web application, follow the steps given below:

  1. In the Choreo Console, go to the top navigation menu, click the Project list, and select the project where you created the web application.
  2. On the project home page, click the web application listed under Component Listing.
  3. In the left navigation menu, click Dependencies and then click Connections.
  4. Create a connection to the API you deployed in Step 1.

Now you can proceed to deploy the web application.

When deploying, if your web application is a single-page application (SPA), you have the option to allow Choreo to handle authentication on behalf of the application. This approach eliminates the need to incorporate OAuth protocol-specific logic into your application.

"},{"location":"authentication-and-authorization/test-secure-api-access-with-choreo-built-in-security-token-service/#test-the-invocation-when-choreo-managed-authentication-is-enabled","title":"Test the invocation when Choreo-managed authentication is enabled","text":"

If managed authentication is enabled for your web application, Choreo automatically handles obtaining the necessary permission for API invocation. This occurs during the request for access tokens, allowing you to seamlessly invoke the subscribed APIs through your web application without additional intervention.

Note

If you change the permissions of an existing connection or create a new connection with permissions, you must redeploy your web application to ensure proper API invocation with managed authentication.

"},{"location":"authentication-and-authorization/test-secure-api-access-with-choreo-built-in-security-token-service/#test-the-invocation-when-the-application-manages-the-authentication","title":"Test the invocation when the application manages the authentication","text":"

If your application manages authentication independently, follow the steps below to generate the necessary OAuth credentials to obtain access tokens:

  1. In the left navigation menu, click Settings. This opens the settings of the web application component.
  2. Click the Authentication Keys tab.
  3. Click on an environment tab depending on the environment for which you want to generate credentials.
  4. Select Choreo Built-In Identity Provider as the identity provider.
  5. Click to expand Advanced Configurations and make sure the code and refresh grant types are selected. This is required to obtain access tokens with an authorization code grant.
  6. Configure the callback URL of the web application to receive the authorization code.
  7. Click Update Configurations.
  8. Click Regenerate Secret and make a note of the client ID and secret that is generated.
  9. Retrieve an access token using the authorization code grant, specifying the necessary OAuth scopes (You can see the endpoint details on the right side).
    • When prompted for authentication, enter the credentials of a user within the built-in identity provider (IdP) who possesses the required assigned groups.
    • Navigate through the OAuth flow to obtain the JWT access token.
  10. Invoke the subscribed API using the access token.
"},{"location":"choreo-cli/choreo-cli-overview/","title":"Choreo Command Line Interface (CLI) Overview","text":"

The Choreo Command Line Interface (CLI) is a command-line tool that helps you easily work with Choreo using commands. By utilizing commands, it significantly improves the development experience for Choreo users. This versatile tool simplifies different stages of the development process, making interactions more efficient and user-friendly.

Choreo serves as a comprehensive internal platform-as-a-service. The Choreo CLI serves as a pivotal tool aimed at enhancing its capabilities. With the Choreo CLI, you can leverage the following benefits:

  • Streamline Deployment Processes: Choreo CLI simplifies the entire process from creating a component in Choreo, building it, to deploying, testing, and monitoring independent of the language and framework used to implement the component.

  • Versatile workflow across frameworks: Regardless of your chosen framework, Choreo CLI offers a uniform end-to-end process. Choreo seamlessly integrates with different web application types (SPA, SSR, SSG, or simple static files), services (REST, GraphQL, gRPC), scheduled jobs, manual triggers, API proxies, and more. This versatility enables you to orchestrate a wide range of cloud-native components seamlessly.

"},{"location":"choreo-cli/choreo-cli-overview/#key-features-of-the-choreo-cli","title":"Key features of the Choreo CLI","text":"

  • Create and Manage Resources: Simplify project and component management. You can easily initiate and organize projects in Choreo through simple commands.

  • Create Builds and Deployments: Simplifies the process of creating builds and deploying components. You can build and promote components to environments easily with simple commands, ensuring a seamless transition from development to deployment.

    Note

    The Choreo CLI currently supports the following component types:

    • Service
    • Web Application
    • Webhook
    • Scheduled Task
    • Manual Task

  • Monitor with Logs : The integrated log functionality in the Choreo CLI allows you to effectively monitor your components. You can access valuable insights into your components behavior and performance directly from the command line.

For troubleshooting tips and answers to frequently asked questions, see the Choreo CLI FAQ.

"},{"location":"choreo-cli/get-started-with-the-choreo-cli/","title":"Get Started with the Choreo CLI","text":"

This guide walks you through the following sample use case:

  • Create a web application
  • Build the web application
  • Deploy the web application in the development environment
  • Promote the web application to the production environment

This guide utilized a simple to-do app built with Next.js and two basic environments: Development and Production.

"},{"location":"choreo-cli/get-started-with-the-choreo-cli/#prerequisites","title":"Prerequisites","text":"

Follow the steps below to install the CLI:

  1. Install the Choreo CLI by running the command specific to your operating system:

    • For Linux and Mac OS 

      curl -o- https://cli.choreo.dev/install.sh | bash\n

    • For Windows (via PowerShell) 

      iwr https://cli.choreo.dev/install.ps1 -useb | iex\n

  2. Verify the installation by running the following command:

    choreo --version\n
"},{"location":"choreo-cli/get-started-with-the-choreo-cli/#step-1-login-to-choreo","title":"Step 1: Login to Choreo","text":"

Run the following command to login to Choreo: 

choreo login\n

Follow the instructions on the console to open the link in the browser and login to Choreo.

"},{"location":"choreo-cli/get-started-with-the-choreo-cli/#step-2-create-a-project","title":"Step 2: Create a project","text":"

A project in Choreo is a logical group of related components that typically represent a single cloud-native application. A project consists of one or more components.

Create a multi-repository project named \u2018web-app-project\u2019 by running the following command:

choreo create project web-app-project --type=multi-repository\n
"},{"location":"choreo-cli/get-started-with-the-choreo-cli/#step-3-create-a-web-application-component","title":"Step 3: Create a Web Application component","text":"

In Choreo, a component within your project represents a singular unit of work in a cloud-native application. It can be a microservice, API, web application, or job/task. Each component is associated with a directory path in a Git repository containing the source code for the program.

Note

The Choreo CLI currently supports the following component types:

  • Service
  • Web Application
  • Webhook
  • Scheduled Task
  • Manual Task

  1. Fork the repository https://github.com/wso2/choreo-sample-todo-list-app. This contains a sample web application that you can use for this guide.

  2. To initiate the creation of a Web Application component within your project, use the following command: This triggers a wizard prompting you to provide details for your Git repository and other configurations for your component.

    choreo create component my-web-app --project=web-app-project --type=webApp\n

  3. Select the option Enter remote repository URL manually.

  4. Enter the following values for the prompts.

    Prompt value Configure source repository Enter remote repository URL manually Remote repository URL Your forked repository Branch main Directory . Build-pack nodejs Language Version 20.x.x Port 8080

    Note

    The prompts may vary based on the type of component and the chosen build pack.

"},{"location":"choreo-cli/get-started-with-the-choreo-cli/#step-4-view-component-details","title":"Step 4: View component details","text":"

To view comprehensive information about the component, including basic details and service endpoint URLs once the services are deployed, you can use the following command:

choreo describe component \"my-web-app\" --project=\"web-app-project\"\n
"},{"location":"choreo-cli/get-started-with-the-choreo-cli/#step-5-build-the-component","title":"Step 5: Build the component","text":"

You must build the components before deploying them to a specific environment. Execute the following command to trigger the build:

choreo create build \"my-web-app\" --project=\"web-app-project\"\n
"},{"location":"choreo-cli/get-started-with-the-choreo-cli/#step-51-view-build-status","title":"Step 5.1: View build status","text":"

To check the status of a specific build, run the following command, replacing with the actual build ID obtained from the previous command:

Note

Typically, a build takes approximately 2 to 5 minutes to complete.

choreo describe build <build-id> --project=\"web-app-project\" --component=\"my-web-app\"\n
"},{"location":"choreo-cli/get-started-with-the-choreo-cli/#step-52-view-build-logs","title":"Step 5.2: View build logs","text":"

Once the build is complete, you can view the build logs for verification or debugging purposes. In the unlikely case, the build encounters any issues, the logs will help you troubleshoot.

choreo logs --type=build --project=\"web-app-project\" --component=\"my-web-app\" --deployment-track=\"main\" --build-id=<build_id>\n
"},{"location":"choreo-cli/get-started-with-the-choreo-cli/#step-6-deploy-to-the-development-environment","title":"Step 6: Deploy to the Development environment","text":"

Once the build status indicates successful you can deploy the component in the Development environment by running the following command:

choreo create deployment \"my-web-app\" --env=Development --project=\"web-app-project\" --build-id=<build-id>\n
"},{"location":"choreo-cli/get-started-with-the-choreo-cli/#step-61-verify-the-deployment-in-the-development-environment","title":"Step 6.1: Verify the deployment in the Development environment","text":"

After deploying the component, you can retrieve the URL of the deployed web application and open the publicly available web page to verify its behavior. Use the following command to retrieve the URL:

choreo describe component \"my-web-app\" --project=\"web-app-project\"\n
"},{"location":"choreo-cli/get-started-with-the-choreo-cli/#step-62-view-runtime-logs","title":"Step 6.2: View runtime logs","text":"

To observe runtime application logs of the web application in the Development environment, execute the following command:

choreo logs --type component-application --component my-web-app --project web-app-project --env Development --follow\n
"},{"location":"choreo-cli/get-started-with-the-choreo-cli/#step-7-deploy-to-the-production-environment","title":"Step 7: Deploy to the Production environment","text":"

Once you verify your application in the Development environment, you can proceed to deploy it to the Production environment with the following command:

  • Be sure to substitute with the id obtained after triggering the build. 
    choreo create deployment \"my-web-app\" --env=Production --project=\"web-app-project\" --build-id=<build-id>\n
    "},{"location":"choreo-cli/get-started-with-the-choreo-cli/#step-71-verify-the-deployment-in-the-production-environment","title":"Step 7.1: Verify the deployment in the Production environment","text":"

    To ensure a successful deployment to the Production environment, retrieve the URL of the deployed web application using the following command:

    choreo describe component \"my-web-app\" --project=\"web-app-project\"\n

    Congratulations! You successfully deployed your web application in Choreo using the Choreo CLI.

    "},{"location":"choreo-cli/get-started-with-the-choreo-cli/#view-all-cli-functions","title":"View all CLI functions","text":"

    Discover other functionalities of Choreo by running the following command.

    choreo --help\n
    "},{"location":"choreo-concepts/choreo-marketplace/","title":"Choreo Marketplace","text":"

    The Choreo Marketplace promotes and facilitates reusing and sharing services. It allows you to share all the services deployed in Choreo. You can easily browse and search available services within the Marketplace and refer to the service definitions, documentation, instructions on how you can use it, etc.

    "},{"location":"choreo-concepts/choreo-marketplace/#discover-services","title":"Discover services","text":"

    The Marketplace includes all services deployed in your organization. This may be a large number of services. Therefore, effective discoverability is desirable.

    You can use the search or apply various filter criteria to explore the services available.

    "},{"location":"choreo-concepts/choreo-marketplace/#search","title":"Search","text":"

    The top search bar provides universal searching to find the services. It allows you to search for a text in the following search attributes:

    • Name: The service name.
    • Label: The service labels.
    • Content: The service content: overview, summary, and documentation.
    • All: All of the above criteria.
    "},{"location":"choreo-concepts/choreo-marketplace/#filter","title":"Filter","text":"

    The Choreo Marketplace provides a filtering capability through the left-hand side filter panel. It allows you to filter with the following filter attributes:

    • Type: This filter enables you to categorize services based on their type, with two available options: \"Internal\" and \"Third-party\". \"Internal\" refers to services deployed within Choreo, while \"Third-party\" refers to services running externally to Choreo, independently added to the Marketplace.

    • Network Visibility: This filter enables you to categorize services based on their network visibility level, with three choices: \"Public,\" \"Organization,\" and \"Project\". \"Public\" filters services exposed publicly, \"Organization\" represents services exposed across the entire organization, and \"Project\" represents services exposed at the project level.

    "},{"location":"choreo-concepts/choreo-marketplace/#explore-a-service","title":"Explore a service","text":"

    You can click on the service card to open the detailed view of the service. The detailed service page features the service name, summary, version, labels, and service icon as the header.

    Choreo organizes the service content into four tabs. The four tabs contain information as follows:

    • Overview: Choreo displays the service overview provided by the service developer. If the service developer has not provided any content at service creation, this section will be disabled. The service developer can provide the overview content via the Manage \u2192 Marketplace section of the component.

    • API definition: Includes the service's API definition, extracted from the user repository using the component-config file or endpoints.yaml file. If the user does not specify an API definition, this tab remains empty.

    • How to use: Includes instructions on how to use the selected service. This includes instructions on creating a connection.

    • Related documents: Includes any additional content the user has provided as documents through the Manage -> Marketplace section of the component.

    "},{"location":"choreo-concepts/choreo-marketplace/#add-a-service-to-the-choreo-marketplace","title":"Add a service to the Choreo Marketplace","text":"

    You can add services to the Marketplace as Choreo services as follows:

    "},{"location":"choreo-concepts/choreo-marketplace/#add-a-choreo-service","title":"Add a Choreo service","text":"

    In Choreo, a service exposed through the platform is termed a Choreo service, with each service being identifiable by an endpoint within a Choreo service component. The Marketplace showcases a service for each endpoint within a service component.

    Upon deployment to the initial environment, services get automatically added to the Marketplace. Choreo effortlessly collects essential details such as component name, endpoint name, description, and service definitions during this deployment, utilizing them to generate the corresponding service entries in the Marketplace.

    The service name follows the convention of component name - endpoint name, while all other details remain unchanged.

    "},{"location":"choreo-concepts/choreo-marketplace/#service-versioning-in-the-choreo-marketplace","title":"Service versioning in the Choreo Marketplace","text":"

    In the Choreo Marketplace, service versions are displayed in their major version format. Each service in the Choreo Marketplace represents the latest version of the service within its major version, following semantic versioning principles.

    For example, if a Choreo service has versions v1.0, v1.1, v1.2, and v2.0, the Choreo Marketplace displays services with versions v1 and v2 representing the latest versions v1.2 and v2.0 respectively.

    When you deploy a new minor version of a service already deployed in Choreo, the corresponding service in the marketplace automatically updates to reflect the latest version within the same major version.

    "},{"location":"choreo-concepts/choreo-marketplace/#semantic-version-based-intelligent-routing-in-the-choreo-marketplace","title":"Semantic-version-based intelligent routing in the Choreo Marketplace","text":"

    When you use a service from the Choreo marketplace as a dependency, the dependent service's traffic automatically routes to the latest version of the corresponding service within the same major version. This ensures that your dependencies remain up-to-date without requiring manual updates within a major version.

    For example, if you create a connection to connect your Choreo component\u00a0named Foo\u00a0to a Choreo service\u00a0named Bar, which is currently available in the Choreo Marketplace as version\u00a0v1, and if\u00a0the latest version of the service Bar within the\u00a0v1\u00a0range is\u00a0v1.2, the component Foo will automatically connect to\u00a0Bar\u00a0v1.2. Subsequently, when Bar\u00a0releases version\u00a0v1.3, traffic from\u00a0Foo\u00a0will automatically route to\u00a0Bar v1.3.

    "},{"location":"choreo-concepts/choreo-marketplace/#edit-services-in-the-choreo-marketplace","title":"Edit services in the Choreo Marketplace","text":"

    You can edit services in the Choreo Marketplace. During redeployment to any environment, Choreo automatically updates service definitions, visibility, and descriptions.

    "},{"location":"choreo-concepts/ci-cd/","title":"CI/CD","text":"

    Choreo provides a streamlined continuous integration and continuous deployment(CI/CD) experience to deploy applications and services efficiently across multiple environments.

    Choreo creates environments for each project, where all components within the project share the environments. An environment is an isolated deployment area with restricted network and resource access. Services deployed in one environment cannot communicate with services deployed in another.

    The Choreo cloud data plane provides two default environments (i.e., development and production). However, if you are in a private data plane organization, you can customize and create multiple environments based on your requirements.

    Choreo adopts a build once, deploy many strategy to manage components across multiple environments. An application is built only once (i.e., per commit if automatic build on commit is enabled or based on the selected commit during a manual build). Then it is promoted to subsequent environments. This allows testing changes in lower, non-production environments like development before promoting the build to production.

    Choreo injects configurations and secrets that you maintain at the environment level into components at runtime. This ensures a strict separation of environment-specific configurations from source code. Although configurations can vary across environments, the code and the built container remain unchanged. Configurations and secrets include:

    • Resource credentials to a database, cache, or other backing services.
    • Credentials to external cloud services such as Amazon S3 or external APIs.

    All configurations and secrets are encrypted at rest and in transit and stored in a secure vault. In a private data plane organization, you can store configurations and secrets in your infrastructure.

    "},{"location":"choreo-concepts/ci-cd/#build","title":"Build","text":"

    Choreo auto-generates build pipelines that may slightly differ depending on the component type you create. Generally, all build pipelines work as follows:

    • Builds a container image either from the provided source code or from a given Dockerfile for a specific commit.
    • Runs security and vulnerability scans if applicable, depending on the component type.
    • Pushes the container image to a container registry. In the cloud data plane, Choreo pushes the image to a Choreo-managed registry. If it is a private data plane organization, Choreo pushes the image to a registry that you own.
    • Updates service endpoints and API specifications from the provided repository if applicable.
    "},{"location":"choreo-concepts/ci-cd/#repeatable-builds","title":"Repeatable builds","text":"

    Choreo can replicate builds from an identical code version (Git commit). This means that multiple builds initiated from the same Git commit will generate Docker images with the same behavior.

    Note

    In the event of multiple builds from the same code version, Choreo preserves only the most recent version of the Docker image created from the particular code version.

    "},{"location":"choreo-concepts/ci-cd/#trigger-a-build","title":"Trigger a build","text":"

    On the Build page, click Build Latest. If necessary you have the option to select a particular commit and build an image.

    If you want to automatically trigger a build with each commit, you can enable\u00a0Auto\u00a0Build\u00a0on Commit.

    "},{"location":"choreo-concepts/ci-cd/#build-logs","title":"Build logs","text":"

    You can view build logs for specific builds on the Build page.

    To view details of a specific build, click View Details corresponding to the build.

    "},{"location":"choreo-concepts/ci-cd/#deployment","title":"Deployment","text":"

    Once you build an image in Choreo, you can deploy it via the Deploy page. To deploy an image, you can follow one of the approaches given below:

    • Manually deploy: In the Deploy page, go to the Set Up card and click Deploy.

    • Automatically deploy on build: In the Deploy page, go to Set Up card and enable Auto\u00a0Deploy on\u00a0Build. This automatically initiates deployment upon the completion of an automatic build.

    Info

    To enable Auto\u00a0Deploy on\u00a0Build, you must enable Auto\u00a0Build\u00a0on Commit. This is because automatic\u00a0deployment is not necessary or useful in scenarios where automatic build is not enabled.

    Note

    • You must trigger the first build in a Ballerina component manually to ensure that Choreo applies the required configurations to the development environment. You can enable automatic builds subsequently.
    • Choreo automatically checks the configurable defined in your source code against the configurable values applied in an environment. Choreo requests the configurable values on deployment and promotion. If you have changed the configurables in your Ballerina component, auto-build pipelines can fail as a precaution to avoid a component crash at runtime due to missing configurables.
    • The configurable verifying capability is only available for Ballerina components. For Dockerfile-based components, ensure to manage and update the configurations and secrets in environments ahead of time. You must also ensure backward compatibility between at least one release if you change the configurations.
    "},{"location":"choreo-concepts/ci-cd/#set-up-area-and-initial-deployment","title":"Set up area and initial deployment","text":"

    In the deploy phase, Choreo uses a setup area to merge the Docker image with its environment-independent configurations. Choreo then deploys this composite to the environment. This is known as the initial deployment.

    "},{"location":"choreo-concepts/ci-cd/#immutable-deployments","title":"Immutable deployments","text":"

    Once Choreo deploys a component with configurations, the configurations become immutable. Any subsequent change results in a new deployment.

    "},{"location":"choreo-concepts/ci-cd/#promote-a-component-to-a-higher-environment","title":"Promote a component to a higher environment","text":"

    Choreo builds a container once per GitHub commit and then promotes it to subsequent higher environments.

    You can go to the Deploy page of a component and promote it manually across environments.

    "},{"location":"choreo-concepts/ci-cd/#configurations","title":"Configurations","text":"

    Choreo allows you to define both environment-independent configurations and environment-specific configurations.

    "},{"location":"choreo-concepts/ci-cd/#environment-independent-configurations","title":"Environment-independent configurations","text":"

    These configurations apply to all environments.

    To change environment-independent configurations, go to the Deploy page of the component, make the necessary configuration changes via the Set Up card, and then trigger a new deployment to the initial environment. From there, you can proceed to promote the component to higher environments.

    "},{"location":"choreo-concepts/ci-cd/#environment-specific-configurations","title":"Environment-specific configurations","text":"

    These configurations apply to a particular environment.

    To change environment-specific configurations, go to the Deploy page of the component, make the necessary configuration changes via the specific environment card, and trigger a new deployment.

    To learn more about managing these configurations, see Configuration Management.

    "},{"location":"choreo-concepts/ci-cd/#task-execution","title":"Task execution","text":"

    The information on the Execute page is only applicable to scheduled and manual task components.

    To track and monitor executions associated with a deployed scheduled task or manual task, go to the left navigation menu and click\u00a0Execute.

    You can view current and historic execution details along with a quick snapshot of recent activity via the total count of executions within the last 30 days. For each execution, you can view vital details such as the unique execution ID, the time it was triggered, and relevant revision information. Furthermore, you can dive deeper into the details by clicking on a specific execution to access its associated logs. This information enhances transparency, troubleshooting capabilities, and overall execution management, allowing you to easily monitor and analyze workflows.

    "},{"location":"choreo-concepts/ci-cd/#zero-downtime-deployments","title":"Zero-downtime deployments","text":"

    Choreo performs rolling updates to ensure zero downtime between deployments and promotions.

    A new build undergoes a health check before traffic is switched to it from the current build.

    If you configure the necessary health checks for a component, it can prevent deploying and promoting unhealthy versions of a component.

    "},{"location":"choreo-concepts/component/","title":"Component","text":"

    A component within a project represents a single unit of work in a cloud native application. A component is usually a single microservice, API, or job/task. Each component in Choreo is attached to a given directory path in a Git repository which either contains program source code or a Dockerfile with build instructions. A component is Choreo\u2019s unit of deployment. Each component maps to a single pod in the Kubernetes cluster (data plane) at deployment time. Therefore, you can deploy, manage, and scale each component in Choreo independently.

    Choreo supports different component types for various use cases. These include component types such as services, API proxies, integrations, web applications, and so on. Each component type hosts unique features based on its characteristics. For example, a scheduled integration component can accept a cron expression as a configuration to schedule an integration job/task.

    "},{"location":"choreo-concepts/connections/","title":"Connections","text":"

    Services can exist in two main forms: standalone and integrated. Connecting services is an integral part in creating integrated solutions. Choreo allows you to connect services using Connections.

    Using Connections, you can integrate the service you intend to deploy on Choreo with other services on Choreo or external resources. Upon creating a connection to a service on Choreo, Choreo provides you a Connection ID along with a set of connection parameters. Thereafter, you have the capability to configure your service to establish a connection using this Connection ID and map connection parameters to environment variable names in your Choreo component. You can read these environment variable names in your service implementation to retrieve the values, to create a programmatic connection to the service you want to consume.

    At runtime, Choreo dynamically injects values into the environment variables based on the configured mapping. This approach ensures that the connection parameter values and the service connection creation remain loosely coupled, providing developers with flexibility and ease of maintenance.

    You can add Connections in different visibility levels: Project and Component. The visibility levels are described below:

    "},{"location":"choreo-concepts/connections/#project-connections","title":"Project Connections","text":"

    Project Connections are Connections you create to connect to services within a particular project. The Connections can be used by any component within the project.

    For example, if you want to share a third-party service like Twilio across the project for all the components within that project to reuse, you can create a project connection. Components can refer to Project Connections using the connection ID. Project connections created to consume Choreo services under the OAuth security scheme will share the same OAuth application across the project. Any component reusing such a connection will use the same client ID and client secret.

    "},{"location":"choreo-concepts/connections/#component-connections","title":"Component Connections","text":"

    Component Connections are Connections you define at the component level and used by only that component.

    For example, create a component connection if you want to connect a legacy service to a given component. Components can refer to the Component Connection using the connection ID. If your component consumes more than one Choreo service, the Component connections created to consume those Choreo services under the OAuth security scheme can share the same OAuth application by sharing the same client ID and secret between all such connections.

    Learn how you can share and reuse services using connections in Choreo.

    "},{"location":"choreo-concepts/data-planes/","title":"Data Planes","text":"

    Choreo's architecture comprises two key components: the control plane and the data plane. The control plane handles essential tasks such as administering organizations, users, and projects. In addition, it also governs the entire journey of application development, from the initial stages of creation, progressing to deployment, including measures to enforce governance and the provision for observability. The Choreo control plane is a SaaS that manages all cloud data planes and private data planes. It caters to diverse user personas, including CIOs, architects, and developers, as well as DevOps, site reliability engineers, and platform engineers.

    The data plane is the environment where user applications are deployed based on configurations set in the control plane. These applications can range from services and web applications to APIs, integrations, and scheduled tasks. The applications can be written in various programming languages, allowing for a polyglot approach. Importantly, all traffic related to the runtime of user applications is restricted to the Choreo data plane, ensuring strict containment of user data within its boundaries.

    Choreo's architecture features two distinct data plane types: cloud data planes and private data planes. A cloud data plane utilizes a multi-tenanted infrastructure model for deploying user applications, creating a shared yet secure environment for application runtime. In contrast, a private data plane(PDP) provides dedicated infrastructure for a single organization to run its user applications. This ensures an added layer of privacy and control for organizations with specific requirements.

    "},{"location":"choreo-concepts/data-planes/#private-data-planes","title":"Private data planes","text":""},{"location":"choreo-concepts/data-planes/#infrastructure","title":"Infrastructure","text":"

    Choreo private data planes can be deployed with almost all major cloud providers, such as Azure, AWS, and GCP, and are also compatible with on-premises infrastructure.

    The essential requirements for a private data plane include upstream-compatible Kubernetes clusters, a container registry, a key vault (secret store), and a logging service or log storage.

    "},{"location":"choreo-concepts/data-planes/#system-components","title":"System components","text":"

    Setting up the Choreo PDP system involves using a Helm installation on the Kubernetes infrastructure. The following software components are installed during the helm execution:

    • Cilium CNI and service mesh.
    • Choreo API Gateways and related components.
    • Choreo PDP agent.
    • Observability and logging APIs, along with observability agents.
    • Flux controller.

    All of these software components receive automatic updates, including security patches and bug fixes through the flux controller connected to the Choreo Update Management System.

    "},{"location":"choreo-concepts/data-planes/#connectivity-with-the-control-plane","title":"Connectivity with the control plane","text":"

    The private data plane requires communication with the Choreo control plane to manage various activities. All these communications are outbound from the private data plane, ensuring that there is no need to open any specific IP:Port from its perspective for these interactions. However, if an organization's network restricts all outbound traffic, it is necessary to permit outbound traffic to the public IP range of the Choreo control plane.

    The following table outlines the inbound and outbound connections from a private data plane:

    Data plane component Endpoint Direction Protocol Choreo PDP agent Choreo control plane (CP) (mizzen server) Outbound WSS Kubernetes API server Outbound (cluster internal) HTTPS, WS APIM/local adaptor Global adaptor Outbound HTTPS Azure Service Bus (CP) Outbound AMQP APIM/Enforcer Event hub (CP) Outbound AMQP Choreo secret resolver Cloud secret store Outbound (VPC internal) HTTPS Container registry Container registry (public) Inbound HTTPS Container registry Outbound (VPC internal) HTTPS Certificate manager Azure DNS service Outbound HTTPS LetsEncrypt Outbound HTTPS Flux source controller GitHub Outbound HTTPS Flux Helm controller Choreo container registry Outbound HTTPS

    All communication between the control plane and the private data plane is secured using TLS.

    "},{"location":"choreo-concepts/data-planes/#observability-architecture","title":"Observability architecture","text":"

    The following diagram depicts the architecture overview of Choreo's in-data-plane log and observability in Azure PDP:

    The private data plane observability architecture is centered around a strong commitment to data privacy and compliance. This is achieved through a strategic decision to retain logs and observability data within the data planes itself. Key aspects of this architecture include:

    • Data storage at source: Logs and observability data are stored within the data plane itself, enhancing security, simplifying access, and ensuring compliance.
    • Direct browser-to-data-plane interaction: The Choreo Console in the user's browser directly interacts with APIs in the data plane, reducing potential data routing complexities and ensuring a more secure, direct flow of information.
    • Reduced data exposure points: Fetching data directly from the data plane's APIs minimizes the number of data transfer points, effectively decreasing the chances of data exposure or interception.
    • Compliance with regulatory standards: The architecture supports data locality, aligning with global regulatory standards like GDPR and CCPA by keeping data in its original environment.
    • Improved performance and real-time insights: Direct interaction between the browser and data plane results in faster data retrieval, providing users with immediate insights.
    • User transparency and control: Users have a clear view of their data's location and access methods, alongside granular control over data access.
    "},{"location":"choreo-concepts/data-planes/#security","title":"Security","text":"

    The Choreo private data plane ensures extensive, production-grade security, ranging from infrastructure and architecture to zero-trust network security. All incoming traffic is protected by a firewall and must undergo authentication and authorization via the API Gateway. It also provides end-to-end network traffic encryption using Cilium transparent encryption, ensuring efficient data path encryption.

    For details on the private data plane security levels supported in Choreo pricing plans, see Private Data Plane Security Levels.

    "},{"location":"choreo-concepts/data-planes/#management-models","title":"Management models","text":"

    Choreo supports the following management models for private data planes (PDPs), fostering collaboration between WSO2 and customers across diverse scenarios:

    • WSO2 fully managed (infrastructure and PDP in WSO2 subscription) model
    • WSO2 fully managed (infrastructure and PDP in customer subscription) model
    • Customer self-managed (WSO2 provides installation script and updates) model

    To explore each management model in detail so that you can make informed decisions depending on the supported cloud-based operations and security, see Private Data Plane Management Models.

    "},{"location":"choreo-concepts/deployment-tracks/","title":"Deployment Tracks","text":"

    Deployment Tracks in Choreo are structured pathways for simplified software component deployment. They act like advanced CI/CD pipelines, ensuring your components reach their destinations seamlessly, whether from source code or prebuilt images. They establish an organized and structured approach that minimizes the chances of errors and challenges that are typically associated with deployment workflows.

    "},{"location":"choreo-concepts/deployment-tracks/#the-significance-of-deployment-tracks","title":"The significance of Deployment Tracks","text":"

    Deployment Tracks offer practical solutions to enhance the API consumer experience by addressing two critical challenges:

    • Streamlined deployment: Deployment Tracks serve as well-designed routes for your software components, enhancing the organization and reliability of the deployment process, similar to a well-structured express route.

    • Efficient API versioning: Especially beneficial for managed APIs, Deployment Tracks provide a straightforward method for creating API versions that seamlessly interact with previous iterations. This simplified version management benefits both API creators and consumers alike.

    "},{"location":"choreo-concepts/deployment-tracks/#streamlined-deployments","title":"Streamlined deployments","text":"

    For streamlined deployments, Choreo dissects two integral approaches that leverage Deployment Tracks: the comprehensive CI/CD integration and the focused CD-Only strategy.

    "},{"location":"choreo-concepts/deployment-tracks/#cicd-with-deployment-tracks","title":"CI/CD with Deployment Tracks","text":"

    A deployment track is linked to a particular branch within a GitHub repository. This connection is useful for handling deployments to various environments. On Choreo's Deploy page, you can easily visualize the deployments to specific environments associated with your selected deployment track. Moreover, the deployment track has a functionality that initiates automatic deployments for the linked branch. When activated, merging a pull request (PR) triggers a deployment to the development environment.

    "},{"location":"choreo-concepts/deployment-tracks/#cd-only-strategy-with-deployment-tracks","title":"CD-Only strategy with Deployment Tracks","text":"

    If you're inclined to use your own Continuous Integration (CI) systems and want to harness the deployment track as a Continuous Deployment (CD) pipeline, you can seamlessly link deployment tracks to a container registry repository. This configuration empowers users to effortlessly deploy images sourced directly from the linked container registry repository.

    "},{"location":"choreo-concepts/deployment-tracks/#efficient-api-versioning","title":"Efficient API versioning","text":"

    This section applies to only service components. When working with service components in Choreo, it is important to have an effective API versioning mechanism. Choreo follows a versioning mechanism based on Semantic Versioning (SemVer) but only includes the major version and minor version with the prefix v.

    For example, v1.2.

    You can follow the approach given below when you version APIs in Choreo:

    • Increment the major version when you make incompatible API changes.
    • Increment the minor version when you add functionality in a backward-compatible manner.

    What is Semantic Versioning?

    Semantic Versioning (SemVer) is a specification that defines how to assign and increment version numbers for software products, including APIs. For more information, see Semantic Versioning specification.

    One of the primary concerns when dealing with SaaS APIs is to minimize disruption for API consumers while continuously developing and deploying updates.

    In compliance with SemVer, changes that don't introduce breaking or additive modifications to the API are categorized as patch updates. Hover, from the perspective of API consumers, these changes should ideally not disrupt their API clients. Typically, API consumers are most concerned with major API version alterations, but there might be instances where minor version changes are communicated to them.

    Therefore, in the context of deployment tracks, API developers only need to specify the major and minor versions being delivered from a particular deployment track. This information is treated as the API version attribute of a deployment track. If the publisher requires versioning for internal tracking purposes, this can be accomplished in Git through the use of Git tags, on GitHub with GitHub releases, and so forth.

    "},{"location":"choreo-concepts/endpoint/","title":"Endpoint","text":"

    An Endpoint is a network-exposed function that resides within a component. In Choreo, service and integration components expose one or more endpoints. Each endpoint in a component can have a service contract (OpenAPI, GraphQL SDL) associated with it. This contract is used to expose the endpoint to consumers. In the absence of a contract, Choreo uses /* exposed on all HTTP verbs as the default contract to expose the service or the integration.

    Each endpoint exposed in a component is considered a single API. Therefore, Choreo allows you to do API management per endpoint for a given component. For example, you can perform lifecycle management and configure security settings per endpoint in a given component.

    See Configure Endpoints to learn how to configure endpoints when developing components in Choreo.

    "},{"location":"choreo-concepts/environments/","title":"Environments","text":"

    Choreo offers developers one or more environments to run their applications within a given data plane. By default, the Choreo cloud data plane provides two environments (i.e., development and production). Each project in Choreo is associated with one or more environments available in the organization. For example, project A may choose to utilize dev, staging, and production environments, while project B may only use development and production environments.

    You can promote components within a project across available environments. When you promote a component, its configuration values can be overridden with environment-specific values.

    The following diagram illustrates how a component is promoted across environments.

    "},{"location":"choreo-concepts/organization/","title":"Organization","text":"

    An organization in Choreo is a logical grouping of users and user resources. A first-time user must create an organization and be a member of it when signing in to Choreo. Users and resources in an organization cannot access resources in another organization unless an admin of the other organization invites them and adds them as a member of that organization. A user cannot create more than one organization.

    "},{"location":"choreo-concepts/organization/#switch-organizations","title":"Switch organizations","text":"

    If you are a member of more than one organization, you can switch from one organization to another when necessary. To do this, select the required organization from the Organization list in the Choreo Console header.

    "},{"location":"choreo-concepts/organization/#inviting-users","title":"Inviting users","text":"

    An organization administrator can invite users to the organization by assigning them specific groups. Invited users receive an invitation via email. An invited user must accept the invitation to join the organization and access the resources of that organization.

    "},{"location":"choreo-concepts/organization/#manage-user-permission","title":"Manage user permission","text":"

    Choreo manages user permissions with groups and roles.

    "},{"location":"choreo-concepts/organization/#groups","title":"Groups","text":"

    A group in Choreo is a collection of users, each with one or more roles assigned to them. Users within a group inherit the permissions associated with the roles assigned to that group. For instance, if a user is added to the API Publisher group, they will automatically receive the API Publisher role.

    Choreo comes with predefined groups already configured with specific roles, as follows:

    • API Publisher: A collection of users who have the API Publisher role.
    • API Subscriber: A collection of users who have the API Subscriber role.
    • Admin : A collection of users who have the Admin role.
    • Billing Admin : A collection of users who have the Billing Admin role.
    • Choreo DevOps : A collection of users who have the Choreo DevOps role.
    • Developer : Users who develop, deploy, and manage cloud native applications at scale.
    • External API Subscriber: A collection of users who have the External API Subscriber role.

    When creating a new group to invite members, be sure to assign a role to the group to ensure users have the required permissions.

    "},{"location":"choreo-concepts/organization/#roles","title":"Roles","text":"

    Choreo roles are defined as follows:

    • API Publisher: An API publisher can discover, create, publish, delete, test, and manage an API.
    • API Subscriber: An API subscriber is a developer in a particular organization. An API subscriber can subscribe to an application, manage subscriptions, manage applications, generate API keys, and manage API keys.
    • Admin: An administrator is responsible for all administration tasks, including user management, customizing the Developer Portal, managing projects, enabling analytics, managing domains, etc.
    • Billing Admin: Is responsible for billing administration that includes viewing tiers, creating and viewing organizations, managing invoices, viewing and creating subscriptions, and viewing and creating payment methods.
    • Choreo DevOps: A Choreo DevOps user is a user with access to the Choreo DevOps portal, enabling them to actively manage, ensure dependable deployment, and monitor components.
    • Developer : A user who can develop, deploy, and manage cloud native applications at scale.
    • External API subscriber: External API subscribers are API consumers who have access only to the API Developer Portal. They can join an organization with the sole purpose of consuming APIs.
    • Environment Manager (Deprecated): Manages deployment environments.
    "},{"location":"choreo-concepts/organization/#organization-id","title":"Organization ID","text":"

    The Organization ID serves as a unique identifier for each organization. To get the organization ID, follow the steps below:

    1. Go to https://console.choreo.dev/ and sign in. This opens the project home page.
    2. Click on the Organization list on the header and select your organization.
    3. In the left navigation, click Settings.
    4. In the header, click the Organization list. This will open the organization level settings page.
    5. Under Organization click Copy ID.
    "},{"location":"choreo-concepts/organization/#organization-handle","title":"Organization Handle","text":"

    The organization handle is a unique string that directly corresponds to your organization's name. To get the organization handle, follow the steps below:

    1. Go to https://console.choreo.dev/ and sign in. This opens the project home page.
    2. Click on the Organization list on the header and select your organization.
    3. In the left navigation, click Settings.
    4. Under Organization click Copy Handle.
    "},{"location":"choreo-concepts/project/","title":"Project","text":"

    A project in Choreo is a logical group of related components that typically represent a single cloud native application. A project consists of one or more components. All components within a project can ideally be (but is not restricted to) in a single GitHub repository under different paths. This is also known as the monorepo architecture.

    At deployment time, all components within a given project are deployed into a single namespace of the Kubernetes cluster. Components within a project can be exposed to the public internet, internally to the rest of the organization, or privately within the project only. A project in Choreo is represented as a cell with regard to the Cell-based architecture. The following diagram illustrates a project and how the components within a project are laid out at runtime:

    "},{"location":"choreo-concepts/resource-hierarchy/","title":"Resource Hierarchy","text":"

    The following diagram depicts the high-level resources and their relationships in Choreo.

    "},{"location":"choreo-concepts/resource-hierarchy/#organizations-and-data-planes","title":"Organizations and data planes","text":"

    Data planes are connected to the organization and are available for all the projects in the organization. When you create an environment in a project, the data plane connected to the organization is linked with an automatically generated Kubernetes namespace.

    "},{"location":"choreo-concepts/resource-hierarchy/#environments-and-data-planes","title":"Environments and data planes","text":"

    Choreo allows multiple Kubernetes clusters to be associated with an environment.

    This allows you to build highly resilient and resource-efficient solutions that utilize multiple clusters. Choreo synchronizes your applications and workloads between associated clusters in an environment. This allows you to perform multi-cluster deployment with a single click.

    The following diagram depicts how multiple clusters associate with different environments:

    Note

    It is not necessary to use a different cluster per environment. You can create multiple environments on the same cluster. The above diagram is only an example of a specific solution. Your application architecture may require an entirely different configuration than what is depicted in the diagram.

    "},{"location":"choreo-concepts/resource-hierarchy/#components-and-environments","title":"Components and environments","text":"

    Components belong to a project in Choreo and environments are provisioned per project as well. When a component is deployed, it is deployed as a container to the specified environment. Once deployed, you can promote the container image across the environments available in the project.

    "},{"location":"consuming-services/consuming-a-sevice/","title":"Consume a Service","text":"

    Choreo is a platform that allows you to create, deploy, and consume services seamlessly. The Choreo Developer Portal simplifies discovering and using APIs for API consumers.

    Typically, an application developer who may be internal or external to your organization would want to consume the APIs published in the Developer Portal to develop their applications. In this guide, you will learn how to discover, generate credentials, and test the consumption of a service published in the Choreo Developer Portal. You will also learn how to invoke the service via a web application.

    This guide walks you through the following steps:

    • Create an application in the Developer Portal and generate credentials for the application.
    • Subscribe the API to the application.
    • Consume a published REST API via your web application.
    "},{"location":"consuming-services/consuming-a-sevice/#prerequisites","title":"Prerequisites","text":"

    Before you try out this guide, if you do not have a published service that you would want to consume via the Developer Portal, follow Develop a Service documentation to publish and deploy a sample REST API.

    "},{"location":"consuming-services/consuming-a-sevice/#discover-apis","title":"Discover APIs","text":"

    In the Choreo Developer Portal, developers can use the search option to find APIs by name. The APIs and services that are created and published through the Choreo Console become visible in the Developer Portal depending on the API's visibility as follows:

    • Public: The API is visible to all in the developer portal.

    • Private: The API is visible to the users who only sign in to the Developer Portal.

    • Restricted: The API is visible to only the user that has the roles that you specify. This option helps developers to enforce fine-grained access control to the API.

    To learn more about API visibility, see Control API Visibility.

    The Choreo Developer Portal lists APIs based on their major version.

    The overview page of an API displays the subscribed versions of the API along with the respective subscription details such as the subscribed application and the application creation date.

    Tip

    If you want to use an API, the recommended approach is to use the latest version of it. You can copy the major version pattern provided as the value of Endpoints(s) on the API overview page and use it in your client application. This ensures that your application always invokes the latest API version.

    "},{"location":"consuming-services/consuming-a-sevice/#create-an-application","title":"Create an application","text":"

    An application in Choreo is a logical representation of a physical application such as a mobile app, web app, device, etc. To consume an API in Choreo, you need to create an application that maps to your physical application and then subscribes to the required API over a usage policy plan that gives you a usage quota. A single application can have multiple subscriptions to APIs. Using the consumer key and consumer secret, you can generate an access token that you can use to invoke all the APIs subscribed to the same application.

    This section walks you through the steps to create an application in Choreo.

    Let's get started!

    "},{"location":"consuming-services/consuming-a-sevice/#step-1-create-an-application","title":"Step 1: Create an application","text":"

    To create an application in the Choreo Developer Portal, follow the steps given below:

    1. Sign in to the Choreo Developer Portal.
    2. Click Applications. and then click +Create.
    3. Enter a name and description for the application.
    4. Click Create.

    This creates the application and opens the application overview page. You can view details such as the token type, workflow status, and the application owner of the API.

    "},{"location":"consuming-services/consuming-a-sevice/#step-2-generate-keys","title":"Step 2: Generate keys","text":"

    Choreo provides an OAuth 2.0 bearer token-based authentication for API access. An API access token/key is a string that is passed as an HTTP header of an API request to authenticate access to the API.

    Once you create an application in Choreo, you can generate credentials for it. When you generate credentials for the first time, Choreo provides a consumer key and consumer secret for the application. The consumer key becomes the unique identifier of the application and is used to authenticate the application.

    The following section walks you through the steps to generate an API access token in Choreo.

    Generate environment-specific keys and tokens

    You can generate keys and tokens to invoke production and non-production endpoints separately.

    Note

    The capability to access production endpoints depends on your role. If you have permission to access production endpoints, you can generate keys and tokens to invoke production endpoints.

    1. In the Choreo Developer Portal header, click Applications.
    2. On the My Applications page, click on the application for which you want to generate keys and tokens.
    3. In the left navigation menu, click the required environment under Credentials. This opens the Application Keys pane of the specific environment.

    4. Click to expand Advanced Configurations and review the options.

      • Grant Types: Select the grant types to use when generating the access token.
      • Public Client: Select Allow authentication without the client secret if your application can be considered as a public client such as an application running on a browser or mobile device.
      • PKCE for enhanced security: Select Mandatory if you want the application to send a code challenge in the authorization request and the corresponding code verifier in the token request. Asgardeo supports SHA-256 and plain.
      • Application access token expiry time: Specify the access token expiry time in seconds.
      • Refresh token expiry time: Specify the refresh token expiry time in seconds.
      • ID token expiry time: Specify the ID token expiry time in seconds.

    5. Click Generate Credentials. This opens the Application Keys pane with values populated for the credentials.

    You can use this consumer key and consumer secret values to generate an API access token by invoking the token endpoint. You can also revoke the access token by invoking the revoke endpoint.

    To generate a test token for testing purposes, you can click Generate Token and copy the test token that is displayed. Alternatively, click cURL and copy the generated cURL command to use via a cURL client and obtain a test token.

    Warning

    Make sure you do not use the test token in your production environment.

    "},{"location":"consuming-services/consuming-a-sevice/#subscribe-to-an-api","title":"Subscribe to an API","text":"

    You must subscribe to a published API to use it in your application. New API subscriptions cover all minor versions within the subscribed API\u2019s major version.

    The subscription process is designed to ensure the secure authentication of API requests via application keys. Alternatively, you can generate credentials for an API without an explicit subscription to an application. However, this approach limits the capability to control advanced configurations such as access token expiry time, revoke token expiry time, ID token expiry time, and enabling access to the API without a secret. Generating keys in the API is recommended for testing or short-term usage but not for long-term production usage.

    To subscribe to an API via an application, follow the steps given below:

    1. Sign in to the Choreo Developer Portal.
    2. In the Developer Portal header, click Applications.
    3. On the My Applications page, click on the application with which you want to subscribe to an API.
    4. In the left navigation menu, click Subscriptions.
    5. In the Subscription Management pane that opens, click + Add APIs.

    6. Click Add to subscribe to an API. Depending on your requirement, you can subscribe to one or more APIs.

      Tip

      When a new minor version of an API is published, the major version-based invocation URL will automatically route to the latest minor version within the subscribed API's major version. This ensures that existing client applications can continue to function without disruption while benefiting from the improvements or additions in the newer minor version.

      Once you subscribe to an API, you can invoke the API using the application keys.

    "},{"location":"consuming-services/consuming-a-sevice/#consume-the-api-via-your-web-application","title":"Consume the API via your web application","text":"

    You can invoke the API/service using the credentials you created above. Since Choreo services are secured, you need to invoke the services securely with the help of your IdP. To invoke the API/service you created securely, you need to follow the steps below:

    1. Create a web application in Choreo.
    2. Create an OAuth application in the IdP.
    3. Configure the web application to authenticate the API/service invocations from the IdP, and securely invoke the service/API in Choreo.
    4. Deploy the web application.

    In this guide, you will be using the following products and examples:

    • WSO2 Asgardeo as the IdP
    • choreo-samples/reading-list-app/reading-list-front-end as the web application. This is a React SPA that invokes the service using Axios. This web application is configured to read the choreo-samples/reading-list-app/reading-list-service as the service. You can modify this web application to read your service, or deploy the choreo-samples/reading-list-app/reading-list-service in Choreo and use it.
    "},{"location":"consuming-services/consuming-a-sevice/#step-1-create-a-web-application-component","title":"Step 1: Create a web application component","text":"

    Info

    You can use your own web application implementation in place of the sample web application. For this exercise, let's use the choreo-samples/reading-list-app/reading-list-front-end as the web application.

    To host the front-end application in Choreo, you must create a web application component. To create a web application component, follow the steps given below.

    1. In the Choreo console, select the project of the reading list application that you created in the previous steps, from the project list located on the header.
    2. Click Create under the Component Listing section to create a new component.
    3. On the Web Application card, click Create.

    4. Enter a unique name and a description for the web application. You can enter the name and description given below:

      Field Value Name Reading List Web App Description Frontend application for the reading list service

    5. Click Next.

    6. To allow Choreo to connect to your GitHub account, click Authorize with GitHub.

    7. In the Connect Repository pane, enter the following information:

      Field Description GitHub Account Your account GitHub Repository choreo-samples Branch main Buildpack Click React since the frontend is a React application built with Vite Build Context Path reading-list-app/reading-list-front-end Build Command npm install && npm run build Build Output dist Node Version 18

    8. Click Create. This initializes the service with the implementation from your GitHub repository and takes you to the Overview page of the component.

    Let's consume the service through the web app. Choreo services are by default secured. To consume a service in Choreo you need an access token. Let's configure the web application to connect to an IdP (For this guide, let's use Asgardeo) to generate an access token for a user.

    "},{"location":"consuming-services/consuming-a-sevice/#step-2-create-an-oauth-application-in-the-idp","title":"Step 2: Create an OAuth application in the IdP","text":"

    To invoke the service/API in Choreo you require a token. To obtain a token you need to create an OAuth application in the IdP. If you use any other IdP other than Asgardeo, create an OAuth application and set the following:

    • Allowed grant types: Code
    • Public client: Mark as a public client in an application.
    • Authorized redirect URLs: Enter the web app URL you copied earlier.
    • Allowed origins field: Add the same URLs that you added as authorized redirect URLs.
    • Access Token: Set JWT as the Token type.

    Choreo uses Asgardeo as the default identity provider for Choreo applications. When you create an application in the Choreo Developer Portal, it automatically creates a corresponding application in Asgardeo. You can go to the Asgardeo application to specify the configurations required for end users to sign in to the front-end application. Follow the steps below to configure the Asgardeo OAuth application:

    1. Access Asgardeo at https://console.asgardeo.io/ and sign in with the same credentials with which you signed in to Choreo.
    2. Make sure you are in the same organization that you were when you created the application in the Choreo Developer Portal. You can click the Organization list in the Asgardeo Console top menu and ensure you are in the correct organization.
    3. In the Asgardeo Console's left navigation, click Applications. You will see the readingListApp that Choreo automatically created for you.
    4. Click on the edit icon to edit the application.

    5. Click the Protocol tab and apply the following changes:

      1. Under Allowed grant types, select Code.
      2. Select the Public client checkbox.
      3. In the Authorized redirect URLs field, enter the web app URL you copied earlier and click the + icon to add the entry.
      4. In the Allowed origins field, add the same URLs that you added as authorized redirect URLs.
      5. Under Access Token, select JWT as the Token type.
      6. Click Update.
    "},{"location":"consuming-services/consuming-a-sevice/#step-3-configure-the-web-application-to-connect-to-the-idp-and-invoke-the-service","title":"Step 3: Configure the web application to connect to the IdP and invoke the service","text":"

    In this step, you are adding the configurations needed for the web app to successfully invoke the Reading List Service REST API. These configurations need to be updated for each environment you deploy the web app. Here you will be updating the configurations for the development environment.

    Note

    The web application is reading the environment-specific configurations from the window object at runtime. This is done via the config.js file in the root of the web application. In this section, you will mount the config.js file for the development environment. You will need to do the same for other environments as well when you deploy your web application to multiple environments.

    To configure the front-end application, follow the steps given below:

    1. While on the web application component page, click DevOps in the left navigation menu and then click Configs and Secrets.
    2. Click + Create.

    3. Select the mount configuration options as follows and click Next:

      Field Description Config Type Config Map Mount Type File Mount

    4. Specify values as follows for the mount configuration:

      Field Description Config Name Web App Config Mount Path /usr/share/nginx/html/config.js. Every config that needs to be exposed through the web server should be placed inside /usr/share/nginx/html/

    5. Copy the config details as a JSON file as shown below into the text area. Fill the placeholders with the values you copied from the previous steps as mentioned in the table below:

      window.config = {\nredirectUrl: \"<web-app-url>\",\nasgardeoClientId: \"<asgardeo-client-id>\",\nasgardeoBaseUrl: \"https://api.asgardeo.io/t/<your-org-name>\",\nchoreoApiUrl: \"<reading-list-service-url>\"\n};\n
      Field Description redirectUrl The web app URL you copied earlier. asgardeoClientId The Client ID of your OAuth application. In Asgardeo, you can find it on the Protocol tab of the readingListApp application asgardeoBaseUrl Specify the IdP API URL (For example, Asgardeo API URL) with your organization name. i.e., https://api.asgardeo.io/t/<ORG_NAME>. choreoApiUrl The reading list service URL. Copy the Public URL of the Reading List Service component from the endpoint table in the overview page for the relevant environment

    6. Click Create.

    Now you can proceed to deploy the web application.

    "},{"location":"consuming-services/consuming-a-sevice/#step-4-deploy-the-web-application","title":"Step 4: Deploy the web application","text":"

    To deploy the web application component, follow the steps below:

    1. In the left menu, click Deploy.
    2. In the Build Area card, click Deploy Manually. The deployment may take a few minutes to complete.
    3. Once the web application is deployed, copy the Web App URL from the development environment card.
    4. Navigate to the web app URL. You can verify that the web app is successfully hosted.

    That's it! You can use a user created in your IdP and invoke the service through your web application.

    "},{"location":"consuming-services/create-a-subscription/","title":"Create a subscription","text":"

    You must subscribe to a published API to use it in your application. New API subscriptions cover all minor versions within the subscribed API\u2019s major version.

    The subscription process is designed to ensure the secure authentication of API requests via application keys. Alternatively, you can generate credentials for an API without an explicit subscription to an application. However, this approach limits the capability to control advanced configurations such as access token expiry time, revoke token expiry time, ID token expiry time, and enabling access to the API without a secret. Generating keys in the API is recommended for testing or short-term usage but not for long-term production usage.

    To subscribe to an API via an application, follow the steps given below:

    1. Sign in to the Choreo Developer Portal.
    2. In the Developer Portal header, click Applications.
    3. On the My Applications page, click on the application with which you want to subscribe to an API.
    4. In the left navigation menu, click Subscriptions.
    5. In the Subscription Management pane that opens, click + Add APIs.

    6. Click Add to subscribe to an API. Depending on your requirement, you can subscribe to one or more APIs.

      Tip

      When a new minor version of an API is published, the major version-based invocation URL will automatically route to the latest minor version within the subscribed API's major version. This ensures that existing client applications can continue to function without disruption while benefiting from the improvements or additions in the newer minor version.

      Once you subscribe to an API, you can invoke the API using the application keys.

    "},{"location":"consuming-services/create-an-application/","title":"Create an application","text":"

    An application in Choreo is a logical representation of a physical application such as a mobile app, web app, device, etc. To consume an API in Choreo, you need to create an application that maps to your physical application and then subscribes to the required API over a usage policy plan that gives you a usage quota. A single application can have multiple subscriptions to APIs. Using the consumer key and consumer secret, you can generate an access token that you can use to invoke all the APIs subscribed to the same application.

    This section walks you through the steps to create an application in Choreo.

    Let's get started!

    "},{"location":"consuming-services/create-an-application/#step-1-create-an-application","title":"Step 1: Create an application","text":"

    To create an application in the Choreo Developer Portal, follow the steps given below:

    1. Sign in to the Choreo Developer Portal.
    2. Click Applications. and then click +Create.
    3. Enter a name and description for the application.
    4. Click Create.

    This creates the application and opens the application overview page. You can view details such as the token type, workflow status, and the application owner of the API.

    "},{"location":"consuming-services/create-an-application/#step-2-generate-keys","title":"Step 2: Generate keys","text":"

    Choreo provides an OAuth 2.0 bearer token-based authentication for API access. An API access token/key is a string that is passed as an HTTP header of an API request to authenticate access to the API.

    Once you create an application in Choreo, you can generate credentials for it. When you generate credentials for the first time, Choreo provides a consumer key and consumer secret for the application. The consumer key becomes the unique identifier of the application and is used to authenticate the application.

    The following section walks you through the steps to generate an API access token in Choreo.

    Generate environment-specific keys and tokens

    You can generate keys and tokens to invoke production and non-production endpoints separately.

    Note

    The capability to access production endpoints depends on your role. If you have permission to access production endpoints, you can generate keys and tokens to invoke production endpoints.

    1. In the Choreo Developer Portal header, click Applications.
    2. On the My Applications page, click on the application for which you want to generate keys and tokens.
    3. In the left navigation menu, click the required environment under Credentials. This opens the Application Keys pane of the specific environment.

    4. Click to expand Advanced Configurations and review the options.

      • Grant Types: Select the grant types to use when generating the access token.
      • Public Client: Select Allow authentication without the client secret if your application can be considered as a public client such as an application running on a browser or mobile device.
      • PKCE for enhanced security: Select Mandatory if you want the application to send a code challenge in the authorization request and the corresponding code verifier in the token request. Asgardeo supports SHA-256 and plain.
      • Application access token expiry time: Specify the access token expiry time in seconds.
      • Refresh token expiry time: Specify the refresh token expiry time in seconds.
      • ID token expiry time: Specify the ID token expiry time in seconds.

    5. Click Generate Credentials. This opens the Application Keys pane with values populated for the credentials.

    You can use this consumer key and consumer secret values to generate an API access token by invoking the token endpoint. You can also revoke the access token by invoking the revoke endpoint.

    To generate a test token for testing purposes, you can click Generate Token and copy the test token that is displayed. Alternatively, click cURL and copy the generated cURL command to use via a cURL client and obtain a test token.

    Warning

    Make sure you do not use the test token in your production environment.

    "},{"location":"consuming-services/generate-an-access-token/","title":"Generate an Access Token","text":"

    Using access tokens for request authorization strengthens security measures, particularly in preventing certain types of denial-of-service (DoS) attacks aimed at published APIs. API consumers generate access tokens to access the API, incorporating them into their HTTP header requests as simple string values.

    When you register an application on the Developer Portal, you can generate a consumer key and a consumer secret for it. The consumer key and the consumer secret represent the credentials of the application. Similar to a user's username, the consumer key becomes the unique identifier of the application so that you can use it to authenticate the request to the API. Choreo issues an access token for the application against the mentioned consumer key.

    This section walks you through the steps to generate an access token for your application in Choreo.

    Let's get started!

    "},{"location":"consuming-services/generate-an-access-token/#prerequisites","title":"Prerequisites","text":"

    Before you try out this guide, be sure you have the following:

    1. An application in the Choreo Developer Portal. If you do not have an application created, create a new application
    2. Generate keys for the application.
    3. Subscribe APIs to the application.
    "},{"location":"consuming-services/generate-an-access-token/#generate-an-access-token-via-curl","title":"Generate an access token via cURL","text":"

    You can follow the steps below to generate an access token for your application via cURL:

    1. In the Choreo Developer Portal header, click Applications.
    2. On the My Applications page, click on the application for which you want to generate the token.
    3. In the left navigation menu, click the required environment under Credentials. This opens the Application Keys pane of the specific environment.
    4. Copy the Consumer Key, Consumer Secret, and Token Endpoint values.

    5. Use the following template and compile the cURL command with the values you copied in the above step.

      Format 

      curl -k -X POST <token_endpoint> -d \"grant_type=client_credentials\" -H \"Authorization: Basic <base64encode(consumer-key:consumer-secret)>\"\n
      6. Execute the cURL command to generate an access token.

    "},{"location":"consuming-services/generate-an-access-token/#generate-an-access-token-via-the-choreo-console-for-testing-purposes","title":"Generate an access token via the Choreo Console (for testing purposes)","text":"

    You can follow the steps below to generate an access token for testing purposes:

    1. In the Choreo Developer Portal header, click Applications.
    2. On the My Applications page, click on the application for which you want to generate keys and tokens.
    3. In the left navigation menu, click the required environment under Credentials. This opens the Application Keys pane of the specific environment.
    4. Click Generate Token.
    "},{"location":"consuming-services/manage-application/","title":"Manage Applications","text":"

    An application in Choreo is a logical representation of a physical application such as a mobile app, web app, device, etc. To consume an API in Choreo, you need to create an application that maps to your physical application and then subscribes to the required API over a usage policy plan that gives you a usage quota. A single application can have multiple subscriptions to APIs. Using the consumer key and consumer secret, you can generate an access token that you can use to invoke all the APIs subscribed to the same application.

    This section walks you through the steps to create an application in Choreo.

    Let's get started!

    "},{"location":"consuming-services/manage-application/#step-1-create-an-application","title":"Step 1: Create an application","text":"

    To create an application in the Choreo Developer Portal, follow the steps given below:

    1. Sign in to the Choreo Developer Portal.
    2. Click Applications. and then click +Create.
    3. Enter a name and description for the application.
    4. Click Create.

    This creates the application and opens the application overview page. You can view details such as the token type, workflow status, and the application owner of the API.

    "},{"location":"consuming-services/manage-application/#step-2-generate-keys","title":"Step 2: Generate keys","text":"

    Choreo provides an OAuth 2.0 bearer token-based authentication for API access. An API access token/key is a string that is passed as an HTTP header of an API request to authenticate access to the API.

    Once you create an application in Choreo, you can generate credentials for it. When you generate credentials for the first time, Choreo provides a consumer key and consumer secret for the application. The consumer key becomes the unique identifier of the application and is used to authenticate the application.

    The following section walks you through the steps to generate an API access token in Choreo.

    Generate environment-specific keys and tokens

    You can generate keys and tokens to invoke production and non-production endpoints separately.

    Note

    The capability to access production endpoints depends on your role. If you have permission to access production endpoints, you can generate keys and tokens to invoke production endpoints.

    1. In the Choreo Developer Portal header, click Applications.
    2. On the My Applications page, click on the application for which you want to generate keys and tokens.
    3. In the left navigation menu, click the required environment under Credentials. This opens the Application Keys pane of the specific environment.

    4. Click to expand Advanced Configurations and review the options.

      • Grant Types: Select the grant types to use when generating the access token.
      • Public Client: Select Allow authentication without the client secret if your application can be considered as a public client such as an application running on a browser or mobile device.
      • PKCE for enhanced security: Select Mandatory if you want the application to send a code challenge in the authorization request and the corresponding code verifier in the token request. Asgardeo supports SHA-256 and plain.
      • Application access token expiry time: Specify the access token expiry time in seconds.
      • Refresh token expiry time: Specify the refresh token expiry time in seconds.
      • ID token expiry time: Specify the ID token expiry time in seconds.

    5. Click Generate Credentials. This opens the Application Keys pane with values populated for the credentials.

    You can use this consumer key and consumer secret values to generate an API access token by invoking the token endpoint. You can also revoke the access token by invoking the revoke endpoint.

    To generate a test token for testing purposes, you can click Generate Token and copy the test token that is displayed. Alternatively, click cURL and copy the generated cURL command to use via a cURL client and obtain a test token.

    Warning

    Make sure you do not use the test token in your production environment.

    "},{"location":"consuming-services/manage-application/#grant-types","title":"Grant types","text":"

    Choreo authentication is based on OAuth 2.0. In OAuth 2.0, grant types are methods that allow client applications to obtain an access token depending on the type of the resource owner, the type of the application, and the trust relationship between the authorization server and the resource owner.

    "},{"location":"consuming-services/manage-application/#authorization-code-grant","title":"Authorization code grant","text":"

    The Authorization code flow provides a secure way for a client application to obtain an access token without exposing the user's credentials to the client application. The user only authenticates with the authorization server, which then issues an authorization code that can be exchanged for an access token.

    This helps to protect user credentials and prevents credentials from being compromised by malicious client applications.

    "},{"location":"consuming-services/manage-application/#refresh-token-grant","title":"Refresh token grant","text":"

    A refresh token is a token that you can use to get a new access token when your current access token is expired or when you need a new access token. You can use the refresh token grant type for this purpose. Issuing a refresh token is optional for the authorization server. If the authorization server issues a refresh token, it includes it in the response with the access token. You can use this refresh token and send it to the authorization server to obtain a new access token. Choreo's default authorization server, Asgardeo, issues refresh tokens for all grant types other than the client credentials grant type, as recommended by the OAuth 2.0 specification.

    Note

    • Keep your refresh token private, similar to the access token.
    • The process to get a new access token using the Refresh Token grant type requires no user interaction.
    "},{"location":"consuming-services/manage-application/#client-credentials-grant","title":"Client credentials grant","text":"

    The client credentials flow provides a secure way for client applications to obtain an access token without user authentication. This is useful in scenarios where the client application needs to access its own resources, such as data storage or APIs, but does not require access to user data. However, it is important to ensure that the client credentials are kept secure because any party who has these credentials can obtain access tokens and access the client's resources.

    "},{"location":"consuming-services/manage-application/#implicit-grant","title":"Implicit grant","text":"

    The implicit grant flow is an OAuth 2.0 grant type that enables a client application to obtain an access token directly from the authorization server without an intermediate authorization code exchange. This flow is commonly used in browser-based applications where the client application runs in a web browser.

    However, it is important to note that the access token is exposed in the browser's URL fragment, which can make it vulnerable to certain types of attacks, such as cross-site scripting (XSS). As a result, this flow is typically not recommended for applications that require high security.

    "},{"location":"consuming-services/manage-application/#password-grant","title":"Password grant","text":"

    The password grant flow is an OAuth 2.0 grant type that enables a client application to obtain an access token by presenting the user's username and password directly to the authorization server. This flow is generally considered less secure than other grant types, as it requires the client application to handle and transmit the user's credentials.

    The password grant is primarily used in scenarios where the client application is highly trusted, and the user experience is prioritized over security concerns. It is generally not recommended for use in public-facing applications or scenarios where sensitive data is accessed.

    "},{"location":"consuming-services/manage-application/#revoke-access-tokens","title":"Revoke access tokens","text":"

    Revoking JWT access tokens can be challenging due to their self-validating nature. Once a token is issued, it contains all the necessary information within itself to validate its authenticity, without requiring additional server-side lookups or interactions.

    It is recommended to use an expiry time that is not more than 900 seconds.

    In traditional session-based authentication, the server can easily revoke a session by invalidating its associated session ID. However, in the case of JWTs, there is no central authority that maintains a list of valid or invalid tokens. As a result, revoking a JWT token requires the use of denylist or allowlist techniques, which can add additional complexity to the authentication flow and may not always be foolproof.

    To mitigate these challenges, it is recommended to use short-lived JWT access tokens and regularly refresh them. This reduces the risk of unauthorized access if a token is stolen or leaked, as the token will expire after a short period of time. Additionally, implementing other security measures such as strong encryption and secure token storage can further enhance the security of JWT-based authentication.

    The Choreo Developer Portal keeps the lifespan of a token to 15 minutes (900 seconds) by default. Application Developers can increase the time if necessary, but as mentioned above, it is recommended to keep it to the minimal possible value.

    "},{"location":"consuming-services/manage-subscription/","title":"Manage Subscriptions","text":"

    You must subscribe to a published API to use it in your application. New API subscriptions cover all minor versions within the subscribed API\u2019s major version.

    The subscription process is designed to ensure the secure authentication of API requests via application keys. Alternatively, you can generate credentials for an API without an explicit subscription to an application. However, this approach limits the capability to control advanced configurations such as access token expiry time, revoke token expiry time, ID token expiry time, and enabling access to the API without a secret. Generating keys in the API is recommended for testing or short-term usage but not for long-term production usage.

    To subscribe to an API via an application, follow the steps given below:

    1. Sign in to the Choreo Developer Portal.
    2. In the Developer Portal header, click Applications.
    3. On the My Applications page, click on the application with which you want to subscribe to an API.
    4. In the left navigation menu, click Subscriptions.
    5. In the Subscription Management pane that opens, click + Add APIs.

    6. Click Add to subscribe to an API. Depending on your requirement, you can subscribe to one or more APIs.

      Tip

      When a new minor version of an API is published, the major version-based invocation URL will automatically route to the latest minor version within the subscribed API's major version. This ensures that existing client applications can continue to function without disruption while benefiting from the improvements or additions in the newer minor version.

      Once you subscribe to an API, you can invoke the API using the application keys.

    "},{"location":"consuming-services/share-applications/","title":"Share Applications","text":"

    Choreo's application-sharing feature allows you to share your applications with members within your organization. This facilitates collaborative efforts when there is a need for multiple members to work on the same application.

    Follow the steps given below to share an application with members of your organization:

    1. Sign in to the Choreo Developer Portal and click the Applications tab.
    2. On the Applications page, click on the application you want to share.
    3. On the Application Overview page that opens, click the Share button displayed on the right side.

    4. In the Share Application dialog, enter one or more email addresses depending on the members with whom you want to share the applications.

      Note

      You must type an email address and press enter for it to get added.

    5. Click Confirm. This will share the application in read-only mode with the specified members.

    To see the members with whom the application is shared, go to the Application Overview page and take a look at the email addresses in the Shared with field.

    "},{"location":"develop-components/bring-your-own-image/","title":"Bring Your Own Image (BYOI)","text":"

    Choreo allows you to deploy and manage prebuilt container images from external container registries as Choreo components. This enables you to deploy and effectively manage your container images within the Choreo environment.

    Info

    This feature is currently only available on private data planes (PDPs) for the following component types:

    • Service
    • Web Application
    • Scheduled Task
    • Manual Task
    "},{"location":"develop-components/bring-your-own-image/#prerequisites","title":"Prerequisites","text":"

    Before you try out this guide, ensure you have the following:

    • A container registry: Ensure you have a container registry containing the images you want to deploy. Choreo is compatible with various container registries, including but not limited to GCR (Google Container Registry), ACR (Azure Container Registry), GitHub Container Registry, and Docker Hub.

    • An image in the registry: You need an image ready for deployment.

    • (Optional) An external build/CI pipeline: This is to initiate automatic deployments during the build process outside of Choreo.

    When using a container registry to deploy a component, Choreo cannot create an image from the source code (Git) or initiate a new deployment when a new image is ready. However, you can use your existing build process to trigger a deployment on Choreo by sending an HTTP POST request to a webhook with the new image details.

    This feature is currently only available on private data planes (PDPs). You can find this option under Deploy an image from a container registry in the Select Source step during component creation for service components, web applications, scheduled tasks, and manual tasks.

    "},{"location":"develop-components/bring-your-own-image/#step-1-register-a-container-registry","title":"Step 1: Register a container registry","text":"

    To get started, establish a connection between your container registry and Choreo.

    Info

    When you use your Choreo credentials, Choreo does not pull your images into its control plane. Instead, it functions as an orchestrator, facilitating your data plane's ability to retrieve images from an external container registry. Choreo passes on these credentials to the data plane for authentication and access.

    To register your container registry, follow these steps:

    1. Sign in to the Choreo Console.
    2. In the Choreo Console header, go to the Organization list and select your organization.
    3. In the left navigation menu, click Settings. This opens the organization settings page.
    4. Click the Credentials tab and then click the Container Registries tab.
    5. Click +Add Registry to configure the Git repository connection.
    6. Specify a Registry Display Name.
    7. Select the Authentication Type. Fill in the required information depending on your authentication type. For details on each authentication type, see Authentication types.
    8. Click Save.
    "},{"location":"develop-components/bring-your-own-image/#authentication-types","title":"Authentication types","text":"

    Choreo provides the following authentication options:

    Public (anonymous) access

    You can use this option to establish a connection with a container registry that permits unrestricted public or anonymous access (for example, Public Docker Hub). In this case, only the registry host information is necessary.

    For example, the following are the Docker Hub registry hosts for reference:

    Vendor Registry host Docker Hub (public repositories) registry.hub.docker.com Docker Hub (private repositories) registry.docker.com

    * If necessary, you can use other mirrors instead of the above.

    Basic authentication

    To use basic authentication to authenticate to the container registry, you must provide the username and password.

    Docker config

    You can provide a Docker config in JSON format to authenticate to the container registry. This option only allows you to register one container registry. That is, it only allows a single registry under auths.

    You must provide the credentials directly within the configuration. Choreo cannot utilize references to executable authentication plugins.

    Sample Docker config format:

        {\n\"auths\": {\n\"index.docker.io/v1/\": {\n\"auth\": \"c3R...zE2\"\n}\n}\n}\n
    Vendor-specific authentication

    This option is specifically for private data planes, where your cloud provider manages authentication at the Kubernetes level. Choreo requires knowledge of the registry host because the data plane already possesses implicit (preconfigured) access to the registry.

    Follow the guidelines below based on your container registry:

    ACRGARAWS ECRDocker Hub (Private)GHCR

    Azure Container Registry

    Recommended authentication options:

    • Service principal-based basic authentication

    • Vendor-specific authentication on Azure private data planes

      Contact Choreo support to enable infrastructure-level private access to your registry from your Azure private data plane on AKS. If you are on a self-managed PDP on Azure, follow this guide.

    Google Artifact Registry

    Recommended authentication options:

    • Service account-based basic authentication

      Use the service account key in JSON format (_json_key) as the username and specify the minified JSON contents of the service account key as the password.

      You can use jq as follows to minify the service account JSON key file:

      jq -c . <service-account.json>

    • Vendor-specific authentication on GCP private data planes

      Contact Choreo support to enable infrastructure-level private access to your registry from your GCP private data plane on GKE. If you are on a self-managed PDP on GCP, see https://cloud.google.com/artifact-registry/docs/access-control#grant-project.

    Elastic Container Registry

    ECR does not allow the creation of static access passwords for basic authentication. The passwords (that is, access tokens) provided by AWS are only valid for 10 hours and must be manually regenerated. However, when an ECR is attached to an EKS cluster at an infrastructure level, this limitation does not apply because the authentication is handled by AWS internally. For details, see https://docs.aws.amazon.com/AmazonECR/latest/userguide/registry_auth.html.

    Choreo recommends using ECR when you are exclusively on an AWS private data plane using the vendor-specific authentication option. Contact Choreo support to enable a private connection between your ECR and the underlying EKS clusters on your data plane. If you are on a self-managed PDP, you can follow this guide.

    Recommended authentication options:

    • Basic authentication

      Use your Docker Hub username/password or an access token. You can generate an access token from your Docker Hub account settings and use it in place of the password. For details, see https://docs.docker.com/docker-hub/access-tokens/.

    • Docker config

      Sign in to the Docker CLI and copy the contents of the docker config JSON. Note that external credential stores and multiple repositories within the same config object are not supported. For more information, see https://docs.docker.com/engine/reference/commandline/login/.

    GitHub Container Registry

    Recommended authentication option:

    • Basic authentication using a PAT token

      Create a personal access token (PAT) and use it in place of the password. You cannot use your own GitHub password. You must provide a PAT token.

    "},{"location":"develop-components/bring-your-own-image/#step-2-create-a-component-in-choreo","title":"Step 2: Create a component in Choreo","text":"
    1. In the left navigation, click Overview and select your project. Alternatively, select your project from the Project list in the Choreo Console header.
    2. Under Component Listing click + Create.
    3. Select your component type (BYOI is only available for Service, Web Application, Scheduled Task, or Manual Task components).

    4. Enter a display name, a unique name, and a description for the component.

      Info

      In the Component Name field, you must specify a name to uniquely identify the component in various contexts. The value is editable only at the time you create the component. You cannot change the name after you create the component.

    5. Click either the Docker Hub tab or the Container Registry tab depending on your vendor.

    6. Under Deploy an image from Container Registry/Docker Hub, select the container registry you have registered in Step 1.

    7. Enter the full image URL. The image URL format in general is as follows: [container-registry-host]/[repository-name]/[image-name]:[tag]

      Tip

      When a public image from Docker Hub lacks a specified repository name, it typically defaults to /library/. For example, you can access the public Nginx image https://hub.docker.com/_/nginx as registry.hub.docker.com/library/nginx:1.25.

    "},{"location":"develop-components/bring-your-own-image/#step-3-deploy-the-component-in-choreo","title":"Step 3: Deploy the component in Choreo","text":"

    To deploy the component and bring your image to Choreo, follow the steps given below:

    1. In the left navigation menu, click Deploy.
    2. In the Build Area card, click Update Image & Deploy.
    3. In the Endpoint pane that opens, you can see the endpoint ready to be deployed. Click the edit icon next to the endpoint name. Optionally, you can define the endpoints for your service when you manually deploy the service. For more information, see Expose service endpoints.
    4. Change the Network Visibility to Public. This setting securely exposes the endpoint for consumption.

    5. Click Update.

      Info

      In this example, you deploy a Ballerina service as a REST endpoint. Therefore, Choreo generated the REST endpoint automatically. If you deploy a non-Ballerina service, you must manually add the REST endpoint and set the network visibility to Public.

    6. Select your update image option. Refer to the update options listed below.

      You have the capability of updating the image when you are deploying the component in Choreo in one of the following three ways:

      Option Description Update Image Tag This option allows you to update the tag of the image. Update Image URL With this option, you can change the image name, tag, and the image repository of the image URL. Previous Images This option allows you to select a previous image and redeploy the image.

    7. Click Deploy. This deploys the service to the development environment.

    "},{"location":"develop-components/bring-your-own-image/#step-4-expose-service-endpoints","title":"Step 4: Expose service endpoints","text":"

    Info

    This section only applies to service components.

    After creating a service component in Choreo, you have the option to define the endpoints for your service when manually deploying a new image.

    1. In the left navigation menu, click Deploy.
    2. In the Build Area card, click Update Image & Deploy.
    3. In the Endpoint pane that opens, optionally, you can define the endpoints for your service when you manually deploy the service.
    4. Click Create/Update Endpoints.
    5. Under the Edit endpoints.yaml section, you can edit the endpoints YAML file in the provided editor. Alternatively, you can upload the associated API specification/schema files (OpenAPI/GraphQL schemas). Instead of specifying the file path, you can also reference this file in the endpoints.yaml file by its file name, similar to the Git-based Choreo components. The endpoints template follows the standard definitions for defining endpoints in Choreo. For more details, see Configure Endpoints.
    "},{"location":"develop-components/bring-your-own-image/#auto-deploy-images-in-choreo-with-an-external-cibuild-pipeline","title":"Auto-deploy images in Choreo with an external CI/build pipeline","text":"

    Choreo does not have automatic detection and deployment for newly added images or tags in the linked container registry. To overcome this limitation, Choreo allows you to integrate your own CI pipelines and initiate deployments manually. This approach enables you to use your existing CI setup or build a pipeline for image creation and pushing. You can then trigger automatic deployments using a webhook.

    Follow the steps below to configure your CI/build pipeline:

    1. Build and push the container image associated with a Choreo component to your container registry.
    2. In the left navigation menu, click DevOps and then click External CI.

    3. Generate a token for your CI pipeline from the Manage Tokens section.

      Note

      • The tokens are bound to a specific component.
      • It is recommended to reference the token from a secure location available to your CI pipeline. For example, use a GitHub secret if you are using GitHub Actions.

    4. To trigger an automatic deployment to your development environment, you can initiate an HTTP POST request to the Choreo webhook endpoint with the updated image details. Alternatively, you can use the provided Webhook snippets. This action will seamlessly deploy the image to the development environment.

    "},{"location":"develop-components/configure-endpoints-body/","title":"Configure endpoints body","text":"

    Services and integrations are exposed to other services, integrations, or applications through endpoints. A service or an integration can expose multiple endpoints, each representing a unique entry point into the service. For example, a service may expose a REST API endpoint and a GraphQL endpoint, each providing different ways to interact with the service. Endpoints provide specific details for how the service or the integration can be consumed. For instance, the port number, protocol, and the schema such as open API specification (OAS) or GraphQL schema. By defining these details, endpoints make it possible for other services, integrations, and applications to discover and interact with the service in a standardized way.

    Choreo defines endpoints by combining port binding, protocol, endpoint name, network visibility, endpoint schema, and additional protocol-related fields. The following table describes each attribute of an endpoint.

    Field Description Name A unique identifier for the endpoint within the service component. Port The network port on which the endpoint is accessible. Type The endpoint protocol. Supported protocols: REST, GraphQL, gRPC, UDP, and TCP. Network Visibility Determines the level of visibility of an endpoint. Possible values are:
    • Project: Allows components within the same project to access the endpoint.
    • Organization: Allows any component within the same organization to access the endpoint but restricts access to components outside the organization.
    • Public: Allows any client to access the endpoint, regardless of location or organization.
    Schema Specifies the structure and format of the data exchanged through the endpoint. Context (HTTP and GraphQL only) A context path that you add to the endpoint's URL for routing purposes."},{"location":"develop-components/configure-endpoints-body/#configure-endpoints","title":"Configure endpoints","text":"

    The method of defining endpoints depends on the buildpack. For buildpacks other than Ballerina and WSO2 MI, it is required to have an endpoints.yaml file in project root directory to create the Service component.

    "},{"location":"develop-components/configure-endpoints-body/#configure-endpoints-with-buildpacks-except-ballerina","title":"Configure endpoints with buildpacks (except Ballerina)","text":"

    When you build a service component using any other buildpacks(Java, Python, NodeJS, Ruby, PHP, Go, Dockerfile, etc) other than Ballerina and WSO2 MI, you can configure the endpoint details with the endpoints.yaml configuration file. You must place this file inside the .choreo directory at the build context path and commit it to the source repository.

    See Understanding the endpoints.yaml file to learn about the endpoints.yaml file.

    "},{"location":"develop-components/configure-endpoints-body/#configure-endpoints-with-the-ballerina-buildpack","title":"Configure endpoints with the Ballerina buildpack","text":"

    When you create a service component with the Ballerina buildpack, Choreo automatically detects the endpoint details for REST APIs. You can override the auto-generated endpoint configuration by providing the endpoints.yaml file in the source directory.

    Note

    Automatic endpoint generation is not supported for dynamic endpoint parameters such as variable ports. Therefore, you must use an endpoint.yaml file to define dynamic endpoint parameters.

    See Understanding the endpoints.yaml file to learn about the endpoints.yaml file.

    "},{"location":"develop-components/configure-endpoints-body/#learn-the-endpointsyaml-file","title":"Learn the endpoints.yaml file","text":"

    The endpoints.yaml file has a specific structure and contains the following details:

    Field 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. type Required The type of traffic this endpoint is accepting, such as REST, GraphQL, gRPC, UDPor 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. 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. Sample endpoints.yaml

    File location:

    <docker-build-context-path>/.choreo/endpoints.yaml\n

    Note

    • For components built with Ballerina buildpack docker-build-context-path should be replaced with component-root. For example: <component-root>/.choreo/endpoints.yaml

    • For components built with WSO2 MI buildpack docker-build-context-path should be replaced with <Project Path>. For example: <Project Path>/.choreo/endpoints.yaml

    File content:

    # +required Version of the endpoint configuration YAML\nversion: 0.1\n# +required List of endpoints to create\nendpoints:\n# +required Unique name for the endpoint. (This name will be used when generating the managed API)\n- name: Greeting Service\n# +required Numeric port value that gets exposed via this endpoint\nport: 9090\n# +required Type of the traffic this endpoint is accepting. Example: REST, GraphQL, etc.\n# Allowed values: REST, GraphQL, GRPC, UDP, TCP\ntype: REST\n# +optional Network level visibility of this endpoint. Defaults to Public\n# Accepted values: Project|Organization|Public.\nnetworkVisibility: Project\n# +optional Context (base path) of the API that is exposed via this endpoint.\n# This is mandatory if the endpoint type is set to REST or GraphQL.\ncontext: /greeting\n# +optional Path to the schema definition file. Defaults to wild card route if not provided\n# This is only applicable to REST endpoint types.\n# The path should be relative to the docker context.\nschemaFilePath: greeting_openapi.yaml\n
    "},{"location":"develop-components/configure-endpoints-body/#apply-advanced-component-connection-configurations","title":"Apply advanced component connection configurations","text":"

    The component-config.yaml file extends the capabilities of endpoints.yaml by introducing enhancements that allow you to apply advanced inbound and outbound connection configurations.

    Beta release

    • The current version of the component-config.yaml file is considered stable. However, it is important to note that the configuration schema may undergo changes and improvements based on user feedback.
    • Support for the current schema will remain even when new versions are introduced.

    The component-config.yaml file complements and enhances the existing endpoint configuration process. It allows you to define how your service's endpoints (inbound connections) are exposed and how your service connects to external services or components (outbound connections).

    • Inbound configurations: This configuration section is for you to define inbound connections, Similar to endpoints.yaml, you can define how your service endpoints are exposed. It aligns seamlessly with the existing endpoint schema structure.

    • Outbound configurations: This configuration section is for you to specify outbound connection details, including service connections. The Choreo Internal Marketplace facilitates creating connections with existing services. To learn more about Choreo Marketplace, see Choreo Marketplace.

    Note

    • If both component-config.yaml and endpoints.yaml are defined in the .choreo path, the component-config.yaml file takes priority.
    • Outbound connections are not supported for deprecated components and WSO2 MI buildpack components.
    "},{"location":"develop-components/configure-endpoints-body/#learn-the-component-configyaml-file","title":"Learn the component-config.yaml file","text":"

    The component-config.yaml file has a specific structure and contains the following details:

    Field Required Description apiVersion Required The version of the component-config.yaml file defaults to core.choreo.dev/v1beta1. kind Required The resource type of the file defaults to ComponentConfig. spec.inbound Optional The list of inbound connection configurations. spec.outbound Optional The list of outbound connection configurations. Inbound connection configurations (spec.inbound)

    In the spec.inbound configuration section, you can specify endpoints to set up inbound connections. To specify endpoints, you can follow the existing endpoints schema structure. For details on the endpoints schema structure, see the endpoints schema documentation.

    Outbound connection configurations (spec.outbound)

    In the spec.outbound section, you can define serviceReferences. To define serviceReferences, you can use the service references generated in the Internal Marketplace when creating a service connection. To copy the outbound connection configurations, see the inline developer guide that is available when you create a connection.

    The serviceReferences schema has a specific structure and contains the following details:

    Field Required Description name Required A unique name for the service reference. connectionConfig Required A unique name for the connection instance. env Optional The list of environment variable mappings that get injected into the container. env.from Required The key name of the connection configuration. env.to Required The environment variable that gets injected into the container.

    Note

    Choreo automatically generates outbound connection configurations upon the creation of a connection within the internal marketplace. The properties such as name, connectionConfig, and env.from are automatically generated. However, you must manually set the env.to value.

    Sample component-config.yaml

    File location:

    <docker-build-context-path>/.choreo/component-config.yaml\n

    Note

    • For components built using the Ballerina buildpack, you must replace docker-build-context-path with the component-root. For example, <component-root>/.choreo/component-config.yaml.
    • For components built using the WSO2 MI buildpack, you must replace docker-build-context-path with the <Project Path>. For example, <Project Path>/.choreo/component-config.yaml.

    File content:

    apiVersion: core.choreo.dev/v1beta1\nkind: ComponentConfig\nspec:\n# +optional Incoming connection details for the component (AKA endpoints).\ninbound:\n# +required Unique name for the endpoint. (This name will be used when generating the managed API)\n- name: Greeting Service\n# +required Numeric port value that gets exposed via the endpoint\nport: 9090\n# +required Type of traffic that the endpoint is accepting. For example: REST, GraphQL, etc.\n# Allowed values: REST, GraphQL, GRPC, TCP, UDP.\ntype: REST\n# +optional Network level visibility of the endpoint. Defaults to Public\n# Accepted values: Project|Organization|Public.\nnetworkVisibility: Public\n# +optional Context (base path) of the API that gets exposed via the endpoint.\n# This is mandatory if the endpoint type is set to REST or GraphQL.\ncontext: /greeting\n# +optional The path to the schema definition file. Defaults to wildcard route if not specified.\n# This is only applicable to REST endpoint types.\n# The path should be relative to the Docker context.\nschemaFilePath: greeting_openapi.yaml\n# +optional Outgoing connection details for the component.\noutbound:\n# +optional Defines the service references from the Internal Marketplace.\nserviceReferences:\n# +required Name of the service reference.\n- name: choreo:///apifirst/mttm/mmvhxd/ad088/v1.0/PUBLIC\n# +required Name of the connection instance.\nconnectionConfig: 19d2648b-d29c-4452-afdd-1b9311e81412\n# +optional Environment variables injected to the component for connection configuration.\nenv:\n# +required Key name of the connection configuration.\n- from: ServiceURL\n# +required Environment variable injected to the container.\nto: SERVICE_URL\n
    "},{"location":"develop-components/configure-endpoints-body/#expose-endpoints-as-managed-apis","title":"Expose endpoints as managed APIs","text":"

    Exposing endpoints as managed APIs is crucial to ensure secure and controlled access to the services being exposed. When a user wants to expose their written service to the outside world or to the organization at large, there is an inherent security risk involved. To mitigate this risk, the Choreo platform is built with an internal (access within the organization only) or external (publicly accessible) gateway that is protected with Choreo API management making the services secure by design.

    Note

    This feature is not available for gRPC, UDP, and TCP endpoints.

    If you want to expose an endpoint as a managed API in Choreo, you need to set the network visibility to either Organization or Public. This allows the endpoint to be exposed through the Choreo API Gateway, which provides a number of benefits, including:

    • Expose APIs to external and internal consumers
    • Full lifecycle API Management
    • API throttling
    • Secure APIs with industry-standard authorization flows
    • API analytics and monitoring

    Once you deploy the service component, Choreo will expose the endpoint as a managed API through the Choreo API Gateway. You can then use the full lifecycle API management features provided by Choreo to test, deploy, maintain, monitor, and manage your API using the API management features.

    "},{"location":"develop-components/configure-endpoints-body/#understand-the-default-component-url","title":"Understand the default component URL","text":"

    The default URL of a component corresponds to the default endpoint of the component and is structured as follows:

    <domain>/<project-name>/<component-name>

    This URL does not include the default endpoint name. For all other endpoints, the URL structure includes the endpoint name, as follows:

    <domain>/<project-name>/<component-name>/<endpoint-name>

    If a component has multiple endpoints, Choreo allows you to change the endpoint corresponding to the default component URL. For a component with a single endpoint, the default URL automatically corresponds to that endpoint.

    "},{"location":"develop-components/configure-endpoints-body/#change-the-default-endpoint-of-a-component","title":"Change the default endpoint of a component","text":"

    To change the default endpoint of a component, follow the steps given below:

    Note

    • You cannot change the default endpoint if it has associated published APIs. You must go to the Lifecycle page and unpublish the relevant APIs before updating the default endpoint. For instructions on unpublishing an API, see Lifecycle Management.
    • Choreo does not allow you to change the default endpoint of a component if you create multiple deployment tracks within its current major version, or promote the component beyond its initial environment.
    1. Sign in to the Choreo Console.
    2. In the Component Listing pane, click on the component for which you want to change the default endpoint.
    3. In the left navigation menu, click Deploy.
    4. On the Deploy page, go to the Set Up card and click Configure & Deploy.
    5. In the Environment Configurations pane that opens, click Next.
    6. In the File Mount pane that opens, click Next.
    7. In the Endpoint Details pane that opens, click the Default Endpoint list, select the endpoint you want to set as the default endpoint, and then click Update.
    8. Click Deploy. This deploys the component with the selected endpoint as the default, and the default URL will now correspond to this endpoint.
    "},{"location":"develop-components/configure-endpoints/","title":"Configure Endpoints","text":"

    Services and integrations are exposed to other services, integrations, or applications through endpoints. A service or an integration can expose multiple endpoints, each representing a unique entry point into the service. For example, a service may expose a REST API endpoint and a GraphQL endpoint, each providing different ways to interact with the service. Endpoints provide specific details for how the service or the integration can be consumed. For instance, the port number, protocol, and the schema such as open API specification (OAS) or GraphQL schema. By defining these details, endpoints make it possible for other services, integrations, and applications to discover and interact with the service in a standardized way.

    Choreo defines endpoints by combining port binding, protocol, endpoint name, network visibility, endpoint schema, and additional protocol-related fields. The following table describes each attribute of an endpoint.

    Field Description Name A unique identifier for the endpoint within the service component. Port The network port on which the endpoint is accessible. Type The endpoint protocol. Supported protocols: REST, GraphQL, gRPC, UDP, and TCP. Network Visibility Determines the level of visibility of an endpoint. Possible values are:
    • Project: Allows components within the same project to access the endpoint.
    • Organization: Allows any component within the same organization to access the endpoint but restricts access to components outside the organization.
    • Public: Allows any client to access the endpoint, regardless of location or organization.
    Schema Specifies the structure and format of the data exchanged through the endpoint. Context (HTTP and GraphQL only) A context path that you add to the endpoint's URL for routing purposes."},{"location":"develop-components/configure-endpoints/#configure-endpoints_1","title":"Configure endpoints","text":"

    The method of defining endpoints depends on the buildpack. For buildpacks other than Ballerina and WSO2 MI, it is required to have an endpoints.yaml file in project root directory to create the Service component.

    "},{"location":"develop-components/configure-endpoints/#configure-endpoints-with-buildpacks-except-ballerina","title":"Configure endpoints with buildpacks (except Ballerina)","text":"

    When you build a service component using any other buildpacks(Java, Python, NodeJS, Ruby, PHP, Go, Dockerfile, etc) other than Ballerina and WSO2 MI, you can configure the endpoint details with the endpoints.yaml configuration file. You must place this file inside the .choreo directory at the build context path and commit it to the source repository.

    See Understanding the endpoints.yaml file to learn about the endpoints.yaml file.

    "},{"location":"develop-components/configure-endpoints/#configure-endpoints-with-the-ballerina-buildpack","title":"Configure endpoints with the Ballerina buildpack","text":"

    When you create a service component with the Ballerina buildpack, Choreo automatically detects the endpoint details for REST APIs. You can override the auto-generated endpoint configuration by providing the endpoints.yaml file in the source directory.

    Note

    Automatic endpoint generation is not supported for dynamic endpoint parameters such as variable ports. Therefore, you must use an endpoint.yaml file to define dynamic endpoint parameters.

    See Understanding the endpoints.yaml file to learn about the endpoints.yaml file.

    "},{"location":"develop-components/configure-endpoints/#learn-the-endpointsyaml-file","title":"Learn the endpoints.yaml file","text":"

    The endpoints.yaml file has a specific structure and contains the following details:

    Field 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. type Required The type of traffic this endpoint is accepting, such as REST, GraphQL, gRPC, UDPor 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. 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. Sample endpoints.yaml

    File location:

    <docker-build-context-path>/.choreo/endpoints.yaml\n

    Note

    • For components built with Ballerina buildpack docker-build-context-path should be replaced with component-root. For example: <component-root>/.choreo/endpoints.yaml

    • For components built with WSO2 MI buildpack docker-build-context-path should be replaced with <Project Path>. For example: <Project Path>/.choreo/endpoints.yaml

    File content:

    # +required Version of the endpoint configuration YAML\nversion: 0.1\n# +required List of endpoints to create\nendpoints:\n# +required Unique name for the endpoint. (This name will be used when generating the managed API)\n- name: Greeting Service\n# +required Numeric port value that gets exposed via this endpoint\nport: 9090\n# +required Type of the traffic this endpoint is accepting. Example: REST, GraphQL, etc.\n# Allowed values: REST, GraphQL, GRPC, UDP, TCP\ntype: REST\n# +optional Network level visibility of this endpoint. Defaults to Public\n# Accepted values: Project|Organization|Public.\nnetworkVisibility: Project\n# +optional Context (base path) of the API that is exposed via this endpoint.\n# This is mandatory if the endpoint type is set to REST or GraphQL.\ncontext: /greeting\n# +optional Path to the schema definition file. Defaults to wild card route if not provided\n# This is only applicable to REST endpoint types.\n# The path should be relative to the docker context.\nschemaFilePath: greeting_openapi.yaml\n
    "},{"location":"develop-components/configure-endpoints/#apply-advanced-component-connection-configurations","title":"Apply advanced component connection configurations","text":"

    The component-config.yaml file extends the capabilities of endpoints.yaml by introducing enhancements that allow you to apply advanced inbound and outbound connection configurations.

    Beta release

    • The current version of the component-config.yaml file is considered stable. However, it is important to note that the configuration schema may undergo changes and improvements based on user feedback.
    • Support for the current schema will remain even when new versions are introduced.

    The component-config.yaml file complements and enhances the existing endpoint configuration process. It allows you to define how your service's endpoints (inbound connections) are exposed and how your service connects to external services or components (outbound connections).

    • Inbound configurations: This configuration section is for you to define inbound connections, Similar to endpoints.yaml, you can define how your service endpoints are exposed. It aligns seamlessly with the existing endpoint schema structure.

    • Outbound configurations: This configuration section is for you to specify outbound connection details, including service connections. The Choreo Internal Marketplace facilitates creating connections with existing services. To learn more about Choreo Marketplace, see Choreo Marketplace.

    Note

    • If both component-config.yaml and endpoints.yaml are defined in the .choreo path, the component-config.yaml file takes priority.
    • Outbound connections are not supported for deprecated components and WSO2 MI buildpack components.
    "},{"location":"develop-components/configure-endpoints/#learn-the-component-configyaml-file","title":"Learn the component-config.yaml file","text":"

    The component-config.yaml file has a specific structure and contains the following details:

    Field Required Description apiVersion Required The version of the component-config.yaml file defaults to core.choreo.dev/v1beta1. kind Required The resource type of the file defaults to ComponentConfig. spec.inbound Optional The list of inbound connection configurations. spec.outbound Optional The list of outbound connection configurations. Inbound connection configurations (spec.inbound)

    In the spec.inbound configuration section, you can specify endpoints to set up inbound connections. To specify endpoints, you can follow the existing endpoints schema structure. For details on the endpoints schema structure, see the endpoints schema documentation.

    Outbound connection configurations (spec.outbound)

    In the spec.outbound section, you can define serviceReferences. To define serviceReferences, you can use the service references generated in the Internal Marketplace when creating a service connection. To copy the outbound connection configurations, see the inline developer guide that is available when you create a connection.

    The serviceReferences schema has a specific structure and contains the following details:

    Field Required Description name Required A unique name for the service reference. connectionConfig Required A unique name for the connection instance. env Optional The list of environment variable mappings that get injected into the container. env.from Required The key name of the connection configuration. env.to Required The environment variable that gets injected into the container.

    Note

    Choreo automatically generates outbound connection configurations upon the creation of a connection within the internal marketplace. The properties such as name, connectionConfig, and env.from are automatically generated. However, you must manually set the env.to value.

    Sample component-config.yaml

    File location:

    <docker-build-context-path>/.choreo/component-config.yaml\n

    Note

    • For components built using the Ballerina buildpack, you must replace docker-build-context-path with the component-root. For example, <component-root>/.choreo/component-config.yaml.
    • For components built using the WSO2 MI buildpack, you must replace docker-build-context-path with the <Project Path>. For example, <Project Path>/.choreo/component-config.yaml.

    File content:

    apiVersion: core.choreo.dev/v1beta1\nkind: ComponentConfig\nspec:\n# +optional Incoming connection details for the component (AKA endpoints).\ninbound:\n# +required Unique name for the endpoint. (This name will be used when generating the managed API)\n- name: Greeting Service\n# +required Numeric port value that gets exposed via the endpoint\nport: 9090\n# +required Type of traffic that the endpoint is accepting. For example: REST, GraphQL, etc.\n# Allowed values: REST, GraphQL, GRPC, TCP, UDP.\ntype: REST\n# +optional Network level visibility of the endpoint. Defaults to Public\n# Accepted values: Project|Organization|Public.\nnetworkVisibility: Public\n# +optional Context (base path) of the API that gets exposed via the endpoint.\n# This is mandatory if the endpoint type is set to REST or GraphQL.\ncontext: /greeting\n# +optional The path to the schema definition file. Defaults to wildcard route if not specified.\n# This is only applicable to REST endpoint types.\n# The path should be relative to the Docker context.\nschemaFilePath: greeting_openapi.yaml\n# +optional Outgoing connection details for the component.\noutbound:\n# +optional Defines the service references from the Internal Marketplace.\nserviceReferences:\n# +required Name of the service reference.\n- name: choreo:///apifirst/mttm/mmvhxd/ad088/v1.0/PUBLIC\n# +required Name of the connection instance.\nconnectionConfig: 19d2648b-d29c-4452-afdd-1b9311e81412\n# +optional Environment variables injected to the component for connection configuration.\nenv:\n# +required Key name of the connection configuration.\n- from: ServiceURL\n# +required Environment variable injected to the container.\nto: SERVICE_URL\n
    "},{"location":"develop-components/configure-endpoints/#expose-endpoints-as-managed-apis","title":"Expose endpoints as managed APIs","text":"

    Exposing endpoints as managed APIs is crucial to ensure secure and controlled access to the services being exposed. When a user wants to expose their written service to the outside world or to the organization at large, there is an inherent security risk involved. To mitigate this risk, the Choreo platform is built with an internal (access within the organization only) or external (publicly accessible) gateway that is protected with Choreo API management making the services secure by design.

    Note

    This feature is not available for gRPC, UDP, and TCP endpoints.

    If you want to expose an endpoint as a managed API in Choreo, you need to set the network visibility to either Organization or Public. This allows the endpoint to be exposed through the Choreo API Gateway, which provides a number of benefits, including:

    • Expose APIs to external and internal consumers
    • Full lifecycle API Management
    • API throttling
    • Secure APIs with industry-standard authorization flows
    • API analytics and monitoring

    Once you deploy the service component, Choreo will expose the endpoint as a managed API through the Choreo API Gateway. You can then use the full lifecycle API management features provided by Choreo to test, deploy, maintain, monitor, and manage your API using the API management features.

    "},{"location":"develop-components/configure-endpoints/#understand-the-default-component-url","title":"Understand the default component URL","text":"

    The default URL of a component corresponds to the default endpoint of the component and is structured as follows:

    <domain>/<project-name>/<component-name>

    This URL does not include the default endpoint name. For all other endpoints, the URL structure includes the endpoint name, as follows:

    <domain>/<project-name>/<component-name>/<endpoint-name>

    If a component has multiple endpoints, Choreo allows you to change the endpoint corresponding to the default component URL. For a component with a single endpoint, the default URL automatically corresponds to that endpoint.

    "},{"location":"develop-components/configure-endpoints/#change-the-default-endpoint-of-a-component","title":"Change the default endpoint of a component","text":"

    To change the default endpoint of a component, follow the steps given below:

    Note

    • You cannot change the default endpoint if it has associated published APIs. You must go to the Lifecycle page and unpublish the relevant APIs before updating the default endpoint. For instructions on unpublishing an API, see Lifecycle Management.
    • Choreo does not allow you to change the default endpoint of a component if you create multiple deployment tracks within its current major version, or promote the component beyond its initial environment.
    1. Sign in to the Choreo Console.
    2. In the Component Listing pane, click on the component for which you want to change the default endpoint.
    3. In the left navigation menu, click Deploy.
    4. On the Deploy page, go to the Set Up card and click Configure & Deploy.
    5. In the Environment Configurations pane that opens, click Next.
    6. In the File Mount pane that opens, click Next.
    7. In the Endpoint Details pane that opens, click the Default Endpoint list, select the endpoint you want to set as the default endpoint, and then click Update.
    8. Click Deploy. This deploys the component with the selected endpoint as the default, and the default URL will now correspond to this endpoint.
    "},{"location":"develop-components/deploy-a-containerized-application/","title":"Deploy a Containerized Application","text":"

    Using Choreo, you can easily deploy applications written in different language frameworks (such as Java, Go, NodeJS, Python, etc.) on shared or private data planes using containers.

    Choreo supports deploying containerized applications for the following component types:

    • Service
    • Web Application
    • Scheduled Task
    • Manual Task
    • Event Handler
    • Test Runner
    "},{"location":"develop-components/deploy-a-containerized-application/#connect-your-repository-to-choreo","title":"Connect your repository to Choreo","text":"

    To connect your GitHub repository to Choreo, you should authorize the Choreo Apps GitHub application to access your account or organization. When you attempt to connect your GitHub repository via the Component creation page, the Choreo Apps authorization prompt will appear.

    • Connect GitHub Repository

    • Authorize GitHub Application

    • Grant Repository Access

      The Choreo Apps requires the following permission:

      • Read access to issues and metadata
      • Read and write access to code, pull requests, and repository hooks

    Note

    You can revoke access if you do not want Choreo to have access to your GitHub account. Choreo needs write access only to send pull requests to a user repository. Choreo does not directly push any changes to a repository.

    Alternatively, you can connect a public repository without requiring authorization from the Choreo Apps GitHub application. You can paste a public repository URL in the Provide Repository URL field at the time of component creation.

    Tip

    Authorizing the repository with the Choreo Apps GitHub application becomes essential if you want to enable Auto Deploy for the component. If you own the repository, you can subsequently authorize it with the Choreo Apps GitHub application to enable Auto Deploy.

    After granting access to the required repositories, you can choose a repository and an associated branch to connect to the Choreo component. For the containerized application deployments, you should select the Dockerfile as the Buildpack and provide Dockerfile Path and Docker Context Path for the Docker build.

    The following table describes the individual fields in the Create Component pane.

    Field Description GitHub Account Your GitHub account or organization. If you want to add another GitHub account, you can expand the list and click + Add. GitHub Repository Depending on the repository access you provided, the list will show available repositories to be connected. Branch The branch of the repository. Buildpack Determines the implementation of the component: Any language or other language as a Docker container. Dockerfile Path The path to your Dockerfile. This path is defined relative to the repository root.For example, if the Dockerfile is at the repository root, the value for this field is /Dockerfile. Docker Context Path The Docker build context path. To include the repository root, leave the default / value. Port* The port at which your service is running. OpenAPI Filepath* The path to an OpenAPI specification (in YAML/JSON) relative to the repository root. If you don't provide a path, the system automatically generates a default allow-all specification.

    Note

    • Fields marked with * are not visible for all component types.

    • To successfully build your container with Choreo, it is essential to explicitly define a User ID (UID) under the USER instruction in your Dockerfile. You can refer to the sample Dockerfile for guidance.

    • To ensure that the defined USER instruction is valid, it must conform to the following conditions:

      • A valid User ID is a numeric value between 10000-20000, such as 10001 or 10500.
      • Usernames are not considered valid and should not be used. For example, my-custom-user-12221 or my-custom-user are invalid User IDs.
    "},{"location":"develop-components/deploy-a-containerized-application/#deploy-the-containerized-component","title":"Deploy the containerized component","text":"

    Choreo will automatically apply deployment configurations and settings based on the component type you select during creation. For example, if you select the Service component type, Choreo will deploy it as a Kubernetes deployment with appropriate scaling configurations.

    You can run unit tests in the build pipeline by adding the relevant command to the Dockerfile. For example:

    • Go-based sample
    • Python-based sample
    "},{"location":"develop-components/deploy-a-containerized-application/#application-configurations","title":"Application configurations","text":"

    You must provide any required configurations for running the application in the Configs & Secrets section of the component's DevOps page. Alternatively, you can also review the configurations when you manually deploy via the Deploy page.

    After clicking the Create button, you can select the confidentiality of the configuration and specify how to mount it to the container.

    Configuration types
    • ConfigMap: Stores non-confidential data as key-value pairs.
    • Secret: Stores and manages sensitive information, such as passwords, OAuth tokens, and ssh keys as key-value pairs.
    Mount types
    • Environment Variables: Mounts the selected ConfigMap or Secret as an environment variable in the container.
    • File Mount: Mounts the selected ConfigMap or Secret as a file in the container. Here, the key is the file name, and the value is the file content.

    The following image shows adding a ConfigMap with File Mount mount type to be read by the application.

    Note

    The JSON file includes ${DB_PASS} as an environment variable defined in a Secret. The application reads the JSON file and substitutes the placeholders with the corresponding environment variables.

    "},{"location":"develop-components/deploy-a-containerized-application/#deployment-configurations","title":"Deployment configurations","text":"

    Choreo lets you configure deployment settings such as scaling, resource limits, and health checks based on your selected component type.

    For more information about these configurations, see Choreo's DevOps capabilities.

    You can configure the Endpoints to expose your service using the Service Component in Choreo. See Service Component Overview for more information.

    "},{"location":"develop-components/deploy-a-containerized-application/#build-deploy-and-promote","title":"Build, deploy, and promote","text":"

    After adding the application configuration, you can build and deploy it by clicking the Deploy Manually button. Choreo will start the build process with the selected commit in the Build Area.

    Note

    The Auto Deploy on Commit feature, which automatically builds and deploys the application upon pushing a code change to the repository, is enabled by default. To turn off this feature, navigate to the Build Area of the Deploy page.

    Choreo scans your Dockerfile for security vulnerabilities during the build phase, and if there are no issues found, it proceeds with the build process. After building the image, it scans it again for vulnerabilities before deployment to the environment. You can view the build logs from the right-side panel, as shown in the image below.

    Once the build process is complete, Choreo will deploy the application automatically to the Development environment. To promote the build to higher environments, you can click the Promote button. The number of environment cards visible on the page may vary depending on your environment configurations.

    "},{"location":"develop-components/deploy-a-containerized-application/#troubleshoot-security-vulnerability-scan-failures-trivy","title":"Troubleshoot security vulnerability scan failures (Trivy)","text":"

    By default, Choreo utilizes the Aqua Trivy (OSS) image vulnerability scanner to detect security vulnerabilities in all Dockerfile-based build pipelines. The scanner will fail the pipeline if any CRITICAL CVEs (Common Vulnerabilities and Exposures) are detected. CVEs of other severity levels are recorded but does not fail the pipeline.

    If you cannot fix a critical CVE immediately, you can opt to ignore it. To ignore a critical CVE, add a trivyignore (<docker-build-context-path>/.trivyignore) file to your build context path. In the file, add the CVEs you need the pipeline to ignore, one entry per line as follows:

    CVE-2023-xxxx\nCVE-2023-yyyy\n

    You can add comments in the file by using # in front of the comment as follows: 

    # comments can be added like this\nCVE-2023-xxxx\n
    "},{"location":"develop-components/deploy-an-application-with-buildpacks/","title":"Deploy an Application with Buildpacks","text":"

    Using Choreo, you can easily deploy applications written in different language frameworks (such as Java, Go, NodeJS, Python, Ruby, PHP, etc.) on shared or private data planes.

    Choreo supports deploying applications with buildpacks for the following component types:

    • Service
    • Web Application
    • Scheduled Task
    • Manual Task
    • Webhook
    • Event Handler
    • Test Runner
    "},{"location":"develop-components/deploy-an-application-with-buildpacks/#buildpacks","title":"Buildpacks","text":"

    Buildpacks are a fundamental building block in modern application development. They convert your source code into a secure, efficient, production-ready container image without a Dockerfile. With Choreo, developers can take advantage of this powerful tool to effortlessly deploy their applications without the hassle of manual configuration.

    Choreo uses Google Buildpacks as default buildpacks for Java, Go, NodeJS, Python, PHP, and Ruby. Choreo uses its own buildpacks for Ballerina and WSO2 MI.

    "},{"location":"develop-components/deploy-an-application-with-buildpacks/#develop-a-component","title":"Develop a component","text":"

    To develop a service component that exposes a Service in Go, you can follow the Develop a Service guide.

    Follow the guidelines below based on your language:

    PythonBallerinaGo.NETJavaNodeJSPHPRubyWSO2 MISpring Boot

    Supported Versions - 3.10.x, 3.11.x

    Refer below examples for different component types. Follow the readme.md inside the example.

    Component Type Example Service Reading Books List Service Manual Task Hello World Task

    Supported Versions - 2201.3.5, 2201.4.1, 2201.5.0, 2201.5.1, 201.6.0, 2201.7.0

    Refer below examples for different component types. Follow the readme.md inside the example.

    Component Type Example Service Echo Service Manual Task Covid19 Statistics To Email Webhook Salesforce New Case To Google Sheet Scheduled Task Shopify New Customers to HubSpot Create/Update Contact

    For more examples, see Choreo samples.

    Supported Versions - 1.x

    Refer below examples for different component types. Follow the readme.md inside the example.

    Component Type Example Service Greeting Service Manual Task Hello World Task Web Application Hello World Web Application

    For more examples, see Choreo samples.

    Supported Versions - 6.x, 7.x, 8.x

    Refer below examples for different component types. Follow the readme.md inside the example.

    Component Type Example Service Greeting Service

    For more examples, see Choreo samples.

    Supported Versions - 8, 11, 17, 18 (OpenJDK Runtime Environment Temurin)

    Refer below examples for different component types. Follow the readme.md inside the example.

    Component Type Example Service Product Management Service Manual Task Hello World Task

    Info

    When working on Java projects:

    • The Main class should be defined in the manifest file.
    • If Maven files such as mvn.cmd exist in the project without the .mvn directory, the build will fail. To ensure a successful build, you must either commit the .mvn directory along with any Maven files or not include any Maven files in the project if you choose not to commit the .mvn directory.
    Procfile

    A Procfile is a configuration file used to declare the commands that are run by your application's containers. If you want to customize the default entry point of the container, you can include a Procfile with the web process type in the project root directory. In Java projects, it is optional to include a Procfile.

    Here's an example Procfile for an application:

    web: <command to start your application>\n

    e.g.,

    web: java -jar target/sample.jar

    For more examples, see Choreo samples.

    Supported Versions - 12.x.x, 14.x.x, 16.x.x, 18.x.x, 20.x.x

    Refer below examples for different component types. Follow the readme.md inside the example.

    Component Type Example Service Reading Books List Service Manual Task Hello World Task Procfile

    A Procfile is a configuration file used to declare the commands that are run by your application's containers. If you want to customize the default entry point of the container, you can include a Procfile with the web process type in the project root directory. In NodeJS projects, it is optional to include a Procfile.

    Here's an example Procfile for an application:

    web: <command to start your application>\n

    e.g.,

    web: node app.js

    For more examples, see Choreo samples.

    Supported Versions - 8.1.x, 8.2.x

    Refer below examples for different component types. Follow the readme.md inside the example.

    Component Type Example Service Hello World Service Manual Task Hello World Task Web Application Hello World Web Application Procfile

    A Procfile is a configuration file used to declare the commands that are run by your application's containers. If you want to customize the default entry point of the container, you can include a Procfile with the web process type in the project root directory. In PHP projects, it is optional to include a Procfile.

    Here's an example Procfile for an application:

    web: <command to start your application>\n

    e.g.,

    web:php -S 0.0.0.0:8000 index.php

    For more examples, see Choreo samples.

    Supported Versions - 3.1.x, 3.2.x

    Refer below examples for different component types. Follow the readme.md inside the example.

    Component Type Example Service Hello World Service Manual Task Hello World Task Web Application Hello World Web Application Procfile

    A Procfile is a configuration file used to declare the commands that are run by your application's containers. If you want to customize the default entry point of the container, you can include a Procfile with the web process type in the project root directory. In Ruby projects, it is optional to include a Procfile.

    Here's an example Procfile for an application:

    web: <command to start your application>\n

    e.g.,

    web: ruby app.rb web:bundle exec ruby app.rb -p 8080

    For more examples, see Choreo samples.

    Supported Versions - 4.1.0.x, 4.2.0.x

    Refer below examples for different component types. Follow the readme.md inside the example.

    Component Type Example Service Hello World Service

    For more examples, see Choreo samples.

    Supported Java Versions - 8, 11, 17, 18 (OpenJDK Runtime Environment Temurin)

    Info

    You can use this buildpack only with web applications. For other component types, use the Java buildpack. Additionally, if the generated artifact is a WAR file, it is necessary to include a Procfile.

    Procfile

    A Procfile is a configuration file used to declare the commands that are run by your application's containers. If you want to customize the default entry point of the container, you can include a Procfile with the web process type in the project root directory. In Java projects, it is optional to include a Procfile.

    Here's an example Procfile for an application:

    web: <command to start your application>\n

    e.g.,

    web: java -jar target/sample.war

    "},{"location":"develop-components/deploy-an-application-with-buildpacks/#procfile","title":"Procfile","text":"

    A Procfile is a configuration file used to declare the commands that are run by your application's containers.

    Info

    In Python projects, it is mandatory to have a Procfile with the web process type in the project root directory.

    Here's an example Procfile for an application:

    web: <command to start your application>\n

    e.g.,

    web: python main.py web: gunicorn --bind :8080 --workers 1 --threads 8 --timeout 0 main:app web: flask run --host=0.0.0.0

    For more examples, see Choreo samples.

    "},{"location":"develop-components/deploy-an-application-with-buildpacks/#configure-build-time-environment-variables","title":"Configure build-time environment variables","text":"

    You can configure the environment variables necessary to build the component using the Build Configurations Editor on the component Build page.

    Info

    The capability to configure build-time environment variables is not available for components created using Ballerina or WSO2 MI buildpacks.

    During the build process, the build-time environment variables and their values are passed to the buildpack. Therefore, you can configure both buildpack-specific environment variables and those required for the component build.

    For example, if you want to override the Maven command of the Java buildpack, you can use GOOGLE_MAVEN_BUILD_ARGS as the environment key and clean install as the value.

    For more examples, see Google Cloud's buildpacks documentation.

    "},{"location":"develop-components/develop-a-webhook/","title":"Develop a Webhook","text":"

    Choreo allows developers to design high-quality webhooks. To explore this capability, let's consider a scenario where a team of software engineers in an organization should be notified via email whenever someone creates a GitHub issue with the bug label in a specific repository.

    In this tutorial, you will address the requirement by doing the following:

    • Create a webhook by connecting to a forked GitHub repository where you have the webhook implementation that addresses the described requirement.
    • Deploy the webhook to the development environment.
    • Modify the webhook implementation to connect the webhook to GitHub, enabling it to act in response to selected GitHub-related events.
    • Test the webhook.
    • Promote the webhook to the production environment.
    "},{"location":"develop-components/develop-a-webhook/#prerequisites","title":"Prerequisites","text":"

    Before you try out the steps in this guide, complete the following:

    • If you are signing in to the Choreo Console for the first time, create an organization as follows:

      1. Go to https://console.choreo.dev/, and sign in using your preferred method.
      2. Enter a unique organization name. For example, Stark Industries.
      3. Read and accept the privacy policy and terms of use.
      4. Click Create. This creates the organization and opens the Project Home page of the default project created for you.

    • Fork the Choreo samples repository, which contains the sample integration for this guide.

    "},{"location":"develop-components/develop-a-webhook/#step-1-create-a-webhook-component","title":"Step 1: Create a Webhook component","text":"

    To create a project, add a Webhook component to it, design the webhook, test it, and then commit it to make it available in the Choreo Console, follow these sub-steps:

    First, let's create a Webhook component as follows:

    1. Go to https://console.choreo.dev/, and sign in using your preferred method.
    2. If you already have one or more components in your project, click + Create. Otherwise, proceed to the next step.
    3. Go to the Webhook card and click Create.
    4. This opens the Create a Webhook pane, where you can specify a name and description for the component. Enter a unique name and description.
    5. Go to the GitHub tab.

    6. To allow Choreo to connect to your GitHub account, click Authorize with GitHub. If you have not already connected your GitHub repository to Choreo, enter your GitHub credentials and select the repository you created in the prerequisites section to install the Choreo GitHub App.

      Alternatively, you can paste the Choreo samples repository URL in the Provide Repository URL field to connect to it without requiring authorization from the Choreo Apps GitHub application. However, authorizing the repository with the Choreo GitHub App is necessary if you want to enable Auto Deploy for the component.

      Note

      The Choreo GitHub App requires the following permissions:

      • Read and write access to code and pull requests.
      • Read access to issues and metadata.

      You can revoke access if you do not want Choreo to have access to your GitHub account. However, write access is exclusively utilized for sending pull requests to a user repository. Choreo will not directly push any changes to a repository.

    7. Select the Access Mode depending on your requirement.

    8. Enter the following information:

      Field Description GitHub Account Your account GitHub Repository choreo-samples Branch main Buildpack Ballerina Project Path github-event-to-email-webhook

    9. Click Create.

    Choreo creates the Webhook component with the sample implementation and opens the component Overview page.

    "},{"location":"develop-components/develop-a-webhook/#step-2-deploy","title":"Step 2: Deploy","text":"

    Let's deploy the webhook to the development environment to make it invokable:

    1. In the Choreo Console left navigation menu, click Deploy.
    2. In the Build Area card, click Configure & Deploy.

    3. In the Configurations pane, enter the following information:

      1. In the webhookSecret field, enter any value.

        Note

        You must save this value for later use.

      2. In the toEmail field, enter the email address to send notification emails.

      3. Click Deploy.

      You can monitor the deployment progress in the Console pane that opens on the right of the page.

    Once Choreo completes the deployment, the Development card indicates the Deployment Status as Active.

    Notes

    In the deployment card, you can click the icon corresponding to configurables to open the Configurations pane and edit configurations:

    "},{"location":"develop-components/develop-a-webhook/#step-3-connect-the-webhook-to-the-github-repository","title":"Step 3: Connect the webhook to the GitHub repository","text":"

    To allow the webhook to read the labels of issues in a specific GitHub repository, you must connect the webhook to the GitHub repository. To do this, follow these steps:

    1. In the Choreo Console left navigation menu, click Overview.

    2. On the Overview page, copy the invoke URL. You can click the copy icon within the URL field.

    3. Go to your GitHub account and open the repository for which you want to generate notification emails.

    4. In the top menu, click the Settings tab.

    5. In the left navigation menu, click Webhooks.

    6. Click Add webhook and enter the following information:

      Field Value Payload URL The invoke URL you copied in Step 3, sub-step 1. Content Type Select application/json Secret The last webhook secret you configured in Step 2.

      Tip

      • Buildpack specifies the type of build to run depending on the implementation of the component. It converts the integration code into a Docker image that can run on Choreo cloud. If an integration is developed using WSO2 Integration Studio, select Micro Integrator as the buildpack. If an integration is developed using the Ballerina language, select Ballerina as the buildpack.

      • Project Path specifies the location of the project to build the component.

    7. Under Which events would you like to trigger this webhook?, select Let me select individual events.

    8. Select the Issues checkbox in the list of events displayed.

      By doing so, you select GitHub issues as events that need to trigger this webhook.

    9. In the same list of events, clear the Pushes checkbox to ensure that GitHub does not trigger your webhook when the team pushes changes to the selected GitHub repository.

    10. Click Add webhook to save the configuration.

    Now you have integrated Choreo with GitHub via the webhook you created and deployed. You can proceed to test the webhook.

    "},{"location":"develop-components/develop-a-webhook/#step-4-test","title":"Step 4: Test","text":"

    To test your webhook, create a GitHub issue with the Bug label in the repository that you connected to the webhook.

    You will receive a mail similar to the following to the email address you provided in Step 2.

    "},{"location":"develop-components/develop-a-webhook/#step-5-promote","title":"Step 5: Promote","text":"

    To promote the webhook to the Production environment, follow these steps:

    1. On the Deploy page, go to the Development card and click Promote.

    2. In the Configuration Types pane, leave the default selection (i.e., Use default configuration values) unchanged.

      If you have configured any default values for the configurable variables, selecting Use default configuration values allows you to proceed with those values.

      If you have not configured any default values for configurable variables, follow the steps given below to specify values.

    3. Click Next.

    4. In the webhookSecret field, enter any value.

      Note

      You must save this value for later use.

    5. In the toEmail field, enter the email address to send notification emails.

    6. Click Promote.

    Once the component is promoted to production, the Production card displays the deployment status as Active.

    Now you have successfully created, deployed, and tested a Webhook component and promoted it to production.

    "},{"location":"develop-components/develop-an-api-proxy/","title":"Develop an API Proxy","text":"

    An API proxy acts as an intermediary between an existing API and Choreo, intercepting all requests made to the API. It also functions as a managed API, which allows you to apply essential API management features such as security policies and rate limiting.

    In this guide, you will:

    • Create an API proxy component to expose an existing API.
    • Deploy the API proxy.
    • Test the API proxy to verify its functionality.
    • Manage the API.
    • Consume the API.
    "},{"location":"develop-components/develop-an-api-proxy/#prerequisites","title":"Prerequisites","text":"

    Before you try out this guide, complete the following:

    • If you are signing in to the Choreo Console for the first time, create an organization as follows:

      1. Go to https://console.choreo.dev/, and sign in using your preferred method.
      2. Enter a unique organization name. For example, Stark Industries.
      3. Read and accept the privacy policy and terms of use.
      4. Click Create.

      This creates the organization and opens the Project Home page of the default project created for you.

    "},{"location":"develop-components/develop-an-api-proxy/#step-1-create-an-api-proxy","title":"Step 1: Create an API proxy","text":"

    To create an API proxy, you can either upload an OpenAPI specification or provide an OpenAPI specification URL. In this guide, you will specify a URL to an OpenAPI definition of a sample API.

    Follow the steps given below:

    1. Go to https://console.choreo.dev/ and sign in. This opens the project home page.
    2. If you already have one or more components in your project, click + Create. Otherwise, proceed to the next step.
    3. Click the API Proxy card. This opens the Create an API Proxy pane, where you can upload an OpenAPI definition or provide the URL of an OpenAPI. In this guide, you will define resources manually. Therefore, click Skip Source to proceed.

    4. Specify the values given in the following table as API proxy details:

      Info

      In the Name field, you must specify a name to uniquely identify the component in various contexts. The value is editable only at the time you create the component. You cannot change the name after you create the component.

      Field Value Display Name HR API Name hr-api Context abc-hr Version 1.0 Target https://samples.choreoapps.dev/company/hr Access Mode External

    5. Click Create.

    This creates the API proxy component and takes you to the Overview page. Now you can proceed to define resources for the API proxy.

    "},{"location":"develop-components/develop-an-api-proxy/#step-2-define-resources-for-the-api-proxy","title":"Step 2: Define resources for the API proxy","text":"

    To add a new resource that can retrieve a department by the department ID, follow the steps given below:

    1. In the left navigation menu, click Develop and then click Resources.
    2. Select GET as the HTTP Verb and enter /department/{departmentId} as the URI Pattern.
    3. Click + to add the resource.

    4. Click to expand the added resource and specify appropriate values for the Operation ID and Description fields. You can specify the values given in the following table:

      Field Value Operation ID findDepartment Description Find a department by department ID

    5. To remove the five default resources that start with /*, click the delete icon corresponding to each resource. This marks the resources for deletion.

    6. Click Save.
    "},{"location":"develop-components/develop-an-api-proxy/#step-3-deploy-the-api-proxy","title":"Step 3: Deploy the API proxy","text":"

    To deploy the API proxy to the development environment, follow the steps given below:

    1. In the left navigation menu, click Deploy.

    2. In the Build Area card, click Configure & Deploy. This opens the Configure & Deploy pane, where you can select the API access mode depending on how you want the API to be accessible. Here, you can select External.

    3. Click Deploy. The Development card indicates the Deployment Status as Active when the API proxy is successfully deployed.

    Now you are ready to test the API proxy.

    "},{"location":"develop-components/develop-an-api-proxy/#step-3-test-the-api-proxy","title":"Step 3: Test the API proxy","text":"

    Choreo allows you to test your API proxy using either the integrated OpenAPI Console or cURL.

    In this guide, you will use the OpenAPI Console to test the API proxy.

    Follow the steps given below:

    Tip

    Choreo enables OAuth 2.0 to secure APIs by default. Therefore, you need an access token to invoke an API.

    • Choreo automatically generates a key to test the API via the OpenAPI Console. To view the key, click the show key icon in the Security Header field.
    • Choreo allows you to disable security for an entire API or a specific API resource for testing purposes. If you want to disable security, follow these steps:
      1. In the left navigation menu, click Deploy.
      2. Go to the Build Area card and click Security Settings.
      3. In the Security Settings pane, perform one of the following actions depending on your requirement:
        • To disable security for the entire API, clear the OAuth2 checkbox.
        • To disable security for a specific API resource, go to the Permissions section, click to expand the relevant resource and then turn off the Security toggle.
      4. Click Apply.

    1. In the left navigation menu, click Test and then click OpenAPI Console.

    2. Select Development from the environment drop-down list.

    3. Expand the GET /department/{departmentId} resource and click Try it Out to test it.

    4. Enter 1 as the departmentId and click Execute. You will see a response similar to the following:

    This indicates that your API proxy is working as expected.

    "},{"location":"develop-components/develop-an-api-proxy/#step-4-manage-the-api-proxy","title":"Step 4: Manage the API proxy","text":"

    Now that you have a tested API proxy, you can publish it and make it available for application developers to consume. Depending on your requirement, you can apply security, throttling, and other settings to the API before you publish it.

    In this guide, you will apply rate limiting to the API and publish it.

    "},{"location":"develop-components/develop-an-api-proxy/#step-41-apply-a-rate-limiting-level-to-the-api-proxy","title":"Step 4.1: Apply a rate limiting level to the API proxy","text":"

    To apply a rate limiting level to the API, follow the steps given below:

    1. In the left navigation menu, click Deploy.
    2. Go to the required environment card and click the setting icon corresponding to API Configuration.
    3. In the API Configuration pane that opens, click Rate Limiting to expand the section.
    4. Select API Level as the Rate Limiting Level.
    5. Specify appropriate values for the Request Limit and Time Unit fields. In this guide, you can proceed with the default values. This applies a rate-limiting policy to the entire API. If necessary, you can also apply rate limits at the operation level. For more information, see API Rate Limiting.
    6. Click Apply. This applies the rate limiting level to the API proxy and redeploys it.
    "},{"location":"develop-components/develop-an-api-proxy/#step-42-publish-the-api-proxy","title":"Step 4.2: Publish the API proxy","text":"

    To publish the API proxy to the Choreo Developer Portal, follow the steps given below:

    1. In the left navigation menu, click Lifecycle under Manage. This takes you to the Lifecycle page where you can see the different lifecycle stages the API can be in. You can see that the current lifecycle stage is Created.
    2. Click Publish.
    3. In the Publish API dialog that opens, click Confirm to proceed publishing the API with the specified display name. If you want to change the display name, make the necessary changes and then click Confirm. This changes the API lifecycle state to Published.
    "},{"location":"develop-components/develop-an-api-proxy/#step-5-invoke-the-api","title":"Step 5: Invoke the API","text":"

    To generate credentials for the published API and to invoke it via the Choreo Developer Portal, follow the steps below:

    1. To open the published API in the Choreo Developer Portal via the Lifecycle page, click Go to Devportal. This takes you to the HR API in the Choreo Developer Portal.

    2. To generate credentials to test the API, follow the steps given below:

      1. In the Developer Portal left navigation menu, click Production under Credentials.

      2. Click Generate Credentials. Choreo generates new tokens and populates the Consumer Key and Consumer Secret fields.

        Tip

        If you want to test the API via an API test tool or through code, click Generate Access Token and copy the test token that is displayed. Alternatively, click cURL and copy the generated cURL command to use via a cURL client. You do not need to generate an access token if you are testing the API via the Try Out capability in the Choreo Developer Portal.

    3. To invoke a resource via the Try Out capability in the Choreo Developer Portal, follow the steps given below:

      1. In the Developer Portal left navigation menu, click Try Out.
      2. In the Endpoint list, select Development as the environment to try out the API.
      3. To generate an access token to try out the API, click Get Test Key. This populates the Access Token field with a test key.
      4. Expand the GET /department/{departmentId} resource and click Try it out.

      5. Enter 1 as the departmentId and click Execute. You will see a response similar to the following:

    Now, you have gained hands-on experience creating, deploying, testing, and publishing an API proxy using Choreo API Manager.

    To learn more about the API management capabilities supported by Choreo API Manager, see API Management.

    "},{"location":"develop-components/develop-components-using-vs-code/","title":"Develop Components Using VS Code","text":"

    The Choreo VS Code extension provides comprehensive component management capabilities to streamline local development within Choreo.

    "},{"location":"develop-components/develop-components-using-vs-code/#prerequisites","title":"Prerequisites","text":"

    To ensure a smooth development experience with the Choreo extension, make sure you have the following:

    1. Visual Studio Code installed with the Choreo extension version 2.0.0 or later.

    2. A locally cloned GitHub repository to create new components or link to existing Choreo components.

    3. Git version 2.0.0 or later.

    "},{"location":"develop-components/develop-components-using-vs-code/#get-started","title":"Get started","text":"

    To use the capabilities of the Choreo extension in the VS Code editor, you need an active Choreo account. If you already have an account, follow these steps to set up the extension:

    1. Install the Choreo VS Code extension and wait for activation. On successful activation, the Choreo extension opens in the VS Code editor.

    2. Sign in to Choreo using one of the following methods:

      • In the Choreo activity pane, click Sign In.
      • Use the Sign In command provided by the Choreo extension.

      This redirects you to an external URI to complete the authentication process. On successful sign-in, the Choreo activity pane displays your account details along with any components detected within the VS Code workspace.

    "},{"location":"develop-components/develop-components-using-vs-code/#create-a-new-component","title":"Create a new component","text":"
    1. Open the source code directory where you want to build, deploy, and manage components using Choreo.

    2. Create a new component using one of the following methods:

      • In the Choreo activity pane, click Create Component.
      • Use the Create New Component command provided by the Choreo extension.

    3. If the Choreo extension cannot determine the project context of the opened workspace, it prompts you to select the organization and the project to which the new component belongs.

    4. Specify component details such as the name, type, buildpack, etc.

      On successful creation, the component details view opens, and the Choreo activity pane displays the new component.

      Tip

      Once the component is created, a .choreo/context.yaml file is generated in the root of the Git repository. For more details, see Understand the project context.

    The component details view allows you to manage your component by performing various actions such as the following:

    • Triggering builds for selected commits.
    • Viewing lists of builds and statuses.
    • Diagnosing build failures with build logs.
    • Deploying builds in available environments.
    • Accessing runtime logs and deployed component URLs.
    • Invoking deployed service endpoints.
    "},{"location":"develop-components/develop-components-using-vs-code/#understand-the-project-context","title":"Understand the project context","text":"

    Context files contain metadata related to the project, allowing the extension to establish an association between local directories and Choreo projects. These files, such as the context.yamlfile, resides in the /.choreo directory within the root of the Git repository.

    The Choreo extension scans the root of the opened Git repository to find the context.yaml file and lists the components of the associated project. This allows you to easily open and manage the components they are developing within the VS Code workspace.

    A context.yaml file can contain multiple projects, whereas, a workspace opened via VS Code can have multiple context.yaml files with different project associations. In such cases, VS Code allows you to switch between these projects, add new project associations, or remove existing ones, allowing you as a developer to focus on components of a particular project at a time.

    You can decide whether to commit the context.yaml file to the Git repository. Committing this file enables other team members working on the same repository to have a seamless developer experience with Choreo.

    If the context.yaml file for a particular project is not committed to the Git repository or is unavailable for other reasons, you can easily regenerate it using one of the following methods:

    • In the Choreo activity pane, click Link Directory.
    • Use the Link Directory command provided by the Choreo extension.
    "},{"location":"develop-components/develop-components-using-vs-code/#discover-additional-features","title":"Discover additional features","text":"

    To access a range of functionalities provided by the Choreo extension, open the VS Code command palette and type Choreo.

    "},{"location":"develop-components/develop-components-using-vs-code/#troubleshoot-issues","title":"Troubleshoot issues","text":"

    To troubleshoot Choreo extension issues, follow these steps:

    1. To open the OUTPUT pane, go to the VS Code editor main menu, click View, and then click Output.

    2. Select Choreo from the drop-down menu on the right-hand side to view the Choreo output for troubleshooting.

    "},{"location":"develop-components/develop-components-using-vs-code/#get-help","title":"Get help","text":"

    For assistance with the Choreo VS Code extension, create GitHub issues.

    "},{"location":"develop-components/develop-components-with-git/","title":"Develop Components With Git","text":"

    Choreo enables you to develop components by connecting your GitHub, Bitbucket, or GitLab repository. You have the flexibility to either connect an existing repository or start with an empty repository and commit the source code later. By integrating your repositories with Choreo, you can automate tasks and optimize workflows across multiple systems, all within the Choreo platform. Choreo currently supports GitHub, Bitbucket, and GitLab as Git providers.

    Tip

    Choreo supports both Bitbucket Server and Bitbucket Cloud. The currently supported Bitbucket Server version is 8.9.2.

    In Choreo, you can connect a Git repository that contains Ballerina source code or a Docker project. To connect a Git repository to Choreo as a Docker project, your Git repository must include the following:

    • A Dockerfile: Specifies the instructions to build the Docker image.
    • A build context: A set of files in the specified path used to build the image.

    Once you connect your Git repository to Choreo, you can build, deploy, and manage your application easily.

    "},{"location":"develop-components/develop-components-with-git/#connect-a-git-repository-to-choreo","title":"Connect a Git repository to Choreo","text":"
    1. Sign in to the Choreo Console.
    2. In the Choreo Console header, go to the Organization list and select your organization.
    3. In the left navigation menu, click Settings. This opens the organization-level settings page.
    4. Click the Credentials tab.
    5. Click +Add Credentials to configure the Git repository connection.
    6. Enter a Credential Name, select the Git provider, and enter the Personal Access Token you obtained from the Git provider.
    7. Click Save.
    "},{"location":"develop-components/develop-components-with-git/#authorize-github-with-choreo","title":"Authorize GitHub with Choreo","text":"

    Authorizing Choreo as a GitHub application grants Choreo the following permissions to perform the respective actions on your behalf within the repository:

    Permission Read Write Description Issues Y N Read component ID label to filter the pull requests Metadata Y N List repositories Contents Y Y List branches and create a branch to commit sample code Pull Request Y Y Create a pull request if you start with a Choreo sample Webhooks Y Y Trigger automatic deployment and configuration generation"},{"location":"develop-components/develop-components-with-git/#add-git-submodules-to-a-project","title":"Add Git submodules to a project","text":"

    Choreo provides Git submodule support when you connect your GitHub repository to Choreo. This allows you to manage and include external repositories effectively within Choreo build pipelines. Key benefits of this capability include:

    • Code sharing without duplication: Use submodules to maintain shared libraries across multiple projects, ensuring a single source of truth.
    • Efficient third-party library management: Manage third-party libraries as submodules to update them independently and track changes easily, avoiding direct code integration.

    For example, when you work with the Micro Integrator (MI) runtime in Choreo, you can use Git submodules to reuse MI templates and sequences across components without duplication.

    Tip

    If you encounter an error stating that you cannot clone a submodule due to insufficient permissions, follow the instructions below to grant the necessary permissions:

    • For a personal account:

      1. Sign in to your personal GitHub account.
      2. In the upper-right corner, click your profile picture, and then click\u00a0Settings.
      3. In the left navigation menu, go to the Integrations section and click Applications.
      4. Under the Installed GitHub Apps tab, click Configure corresponding to choreo.dev.
      5. Under Repository Access, grant access to the necessary repositories.

    • For an organization account:

      1. Sign in to your organization's GitHub account.
      2. In the upper-right corner, click your profile picture, and then click\u00a0Settings.
      3. In the left navigation menu, go to the Third-Party Access section and click GitHub Apps.
      4. Click Configure corresponding to choreo.dev.

      5. Under Repository Access, grant access to the necessary repositories.

        Note

        Choreo currently does not support accessing private repositories in other organizations.

    "},{"location":"develop-components/develop-components-with-git/#authorize-bitbucket-with-choreo","title":"Authorize Bitbucket with Choreo","text":"

    Authorizing using a personal access token (PAT) from Bitbucket grants Choreo the following permissions to perform the respective actions on your behalf within the repository.

    Permission Read Write Description Account Y N Get user information and workspace details Repositories Y Y List branches and create a branch to commit sample code Pull Requests Y Y Create a pull request if you start with a Choreo sample Webhooks Y Y Trigger automatic deployment and configuration generation"},{"location":"develop-components/develop-components-with-git/#authorize-self-managed-gitlab-with-choreo","title":"Authorize self-managed GitLab with Choreo","text":"

    Authorizing using a personal access token (PAT) obtained from your GitLab self-managed server grants Choreo the following permissions to perform the respective actions on your behalf within the repository.

    Permission Description API Grants full read/write access to the API, covering all groups and projects, as well as read/write access to the repository."},{"location":"develop-components/manage-deployment-tracks-for-choreo-components/","title":"Manage Deployment Tracks for Choreo Components","text":"

    Choreo allows you to create and manage dedicated deployment tracks for components, facilitating independent version control and deployment. This capability also allows you to unlink deployment tracks from associated branches or relink them to different branches so that you can align with your preferred Git workflows, such as the feature branch workflow or GitFlow workflow.

    Info

    Deployment track creation and management does not apply to API Proxy and BYOI components.

    "},{"location":"develop-components/manage-deployment-tracks-for-choreo-components/#create-a-deployment-track","title":"Create a deployment track","text":"

    Prerequisites:

    • Create a component in Choreo.

    Follow the steps below to create a deployment track for a component:

    1. Sign in to the Choreo Console.
    2. In the Component Listing pane, click on the component you want to create a deployment track for.
    3. On the header of the component overview page, click the Deployment Track drop-down list.
    4. Click + Create New to open the Create Deployment Track dialog.
    5. In the Create Deployment Track dialog, do the following:
      1. Select a branch to associate with the deployment track.
      2. Optionally, specify a description for the deployment track.
      3. To create a deployment track for a service component, specify a unique API version indicating the major and minor version numbers.
    6. Click Create.
    "},{"location":"develop-components/manage-deployment-tracks-for-choreo-components/#unlink-a-deployment-track","title":"Unlink a deployment track","text":"

    If you want to detach a branch reference from a deployment track, you must unlink the branch.

    Info

    When you unlink the branch of a deployment track, the active deployments are unaffected. However, while you can redeploy the existing deployment, you cannot perform a new deployment.

    Follow the steps below to unlink a deployment track of a component:

    1. Sign in to the Choreo Console.
    2. In the Component Listing pane, click on the component for which you want to unlink a deployment track.
    3. On the header of the component overview page, click the Deployment Track drop-down list and then click View All. This takes you to the component settings page where you can see all the deployment tracks linked to the component.
    4. Click the edit icon corresponding to the deployment track you want to unlink.
    5. In the Edit Branch dialog that opens, click the Branch Name list and select None.
    6. Click Save.
    "},{"location":"develop-components/manage-deployment-tracks-for-choreo-components/#link-a-deployment-track","title":"Link a deployment track","text":"

    To associate a branch reference to an unlinked deployment track, you must link a branch.

    Info

    To build and deploy the contents of the linked branch, you must perform a manual build and deploy.

    Prerequisites:

    • A minimum of two branches in your GitHub repository.

    Follow the steps below to link a branch to an unlinked deployment track:

    1. Sign in to the Choreo Console.
    2. In the Component Listing pane, click on the component you want to associate a branch reference for.
    3. On the header of the component overview page, click the Deployment Track drop-down list and then click View All. This takes you to the component settings page where you can see all the deployment tracks linked to the component.
    4. Click + Link Branch corresponding to the unlinked deployment track for which you want to associate a branch.
    5. In the Link Branch dialog that opens, click the Branch Name list and select the branch you want to relink.
    6. Click Save.
    "},{"location":"develop-components/manage-deployment-tracks-for-choreo-components/#relink-a-deployment-track","title":"Relink a deployment track","text":"

    To switch the branch reference of a linked deployment track, you must relink to an appropriate branch.

    Info

    If you unlink the existing branch of a deployment track and link a different branch, you must perform a manual build and deploy to build and deploy the contents of the recently linked branch.

    Prerequisites:

    • A minimum of two branches in your GitHub repository.

    Follow the steps below to switch the branch reference of a linked deployment track:

    1. Sign in to the Choreo Console.
    2. In the Component Listing pane, click on the component you want to relink a deployment track for.
    3. On the header of the component overview page, click the Deployment Track drop-down list and then click View All. This takes you to the component settings page where you can see all the deployment tracks linked to the component.
    4. Click the Edit Branch icon corresponding to the deployment track you want to relink.
    5. In the Edit Branch dialog that opens, click the Branch Name list and select the branch you want to relink.
    6. Click Save.

    Now that you understand how to create and manage deployment tracks for components, let\u2019s explore a sample scenario to see how a developer can use deployment tracks to manage version releases in Choreo.

    "},{"location":"develop-components/manage-deployment-tracks-for-choreo-components/#sample-scenario-manage-version-releases-with-deployment-tracks","title":"Sample Scenario: Manage version releases with deployment tracks","text":"

    Let\u2019s consider the following version release scenario:

    • To initiate work on a new feature, a developer creates a new branch, named feature-x from either the main or dev branch.
    • Once development is complete, the developer proceeds to merge the feature-x branch into the dev branch for testing.
    • Upon successful testing in the dev branch, the developer proceeds to merge all the changes into the main branch for production deployment.

    Following are the actions you need to take from a deployment track perspective to manage the version release:

    1. To prepare for the new version release, unlink the main branch from the associated deployment track (let\u2019s consider this as the deployment track 1).
    2. Proceed to merge the dev branch containing the tested changes into the main branch.
    3. Unlink the dev branch from the associated deployment track (let\u2019s consider this as deployment track 2).
    4. Link deployment track 2 containing the latest version of the service to the main branch for deployment.
    5. To facilitate ongoing development and testing, create another deployment track (let\u2019s consider this as deployment track 3) and link it to the dev branch.

    Tip

    • As a developer, you can strategically unlink and relink deployment tracks to effectively manage different versions of your services within Choreo.
    • You can create new deployment tracks for ongoing development branches like dev to ensure a continuous development and release cycle.
    "},{"location":"develop-components/manage-deployment-tracks-for-choreo-components/#delete-a-deployment-track","title":"Delete a deployment track","text":"

    If you no longer need a deployment track, you can delete it.

    Note

    If the component exposes an endpoint or proxy and you want to delete the last version in the major version range, the recommended approach is to retire that version first. This allows consumers to transition to the next major version and prevents a sudden break in their experience. For example, if you have deployment tracks for v1.0 and v2.0, notify consumers to switch to v2.0 before deleting v1.0. Then, retire the APIs in v1.0 and proceed to delete the associated deployment track.

    Prerequisites:

    • At least 2 deployment tracks in a component.

    Follow the steps below to delete a deployment track:

    1. Sign in to the Choreo Console.
    2. In the Component Listing pane, click on the component for which you want to delete a deployment track.
    3. On the header of the component overview page, click the Deployment Track drop-down list.
    4. Click + View All. This takes you to the component settings page where you can see all the deployment tracks linked to the component.
    5. Click the Delete icon corresponding to the deployment track you want to delete.
    6. Click Delete to confirm the deletion.
    "},{"location":"develop-components/manage-the-micro-integrator-runtime-version-in-your-integration-project/","title":"Manage the Micro Integrator Runtime Version in Your Integration Project","text":"

    Choreo allows you to use a preferred WSO2 Micro Integrator (MI) runtime version in your integration project. Currently, Choreo supports MI product versions 4.1.0 and 4.2.0. You have the flexibility to deploy WSO2 updates within these specified versions.

    When you create an integration project, you can specify a required runtime version to gain control over the environment in which your integration runs. This version management capability empowers you to tailor your projects depending on your runtime requirements, enhancing the customization and adaptability of your integration workflows.

    "},{"location":"develop-components/manage-the-micro-integrator-runtime-version-in-your-integration-project/#understand-the-version-string","title":"Understand the version string","text":"

    WSO2 Micro Integrator (MI) utilizes a versioning system consisting of three-digit numbers, such as 4.1.0 and 4.2.0, following semantic versioning principles. The product remains committed to receiving updates from WSO2, including security fixes, bug resolutions, and enhancements. Within the Choreo platform, the MI runtime version is constructed by combining the product release version with its corresponding update level.

    In Choreo, the MI runtime version is structured as a four-digit number, for example, 4.1.0.14 or 4.2.0.17. The first three digits represent the product release version, while the last digit signifies the update level of the product. The fourth digit is optional and can be omitted.

    "},{"location":"develop-components/manage-the-micro-integrator-runtime-version-in-your-integration-project/#version-management-in-wso2-integration-studio","title":"Version management in WSO2 Integration Studio","text":"

    If you are using WSO2 Integration Studio to build and deploy integration artifacts in WSO2 Micro Integrator, you can create multiple runtime environments and execute projects on any selected environment. WSO2 Integration Studio also allows you to configure multiple Micro Integrator runtime environments, offering flexibility and customization in the execution of integration processes.

    You can specify the Runtime version when you create an integration project in WSO2 Integration Studio. In the project creation wizard, specify the runtime version in the Runtime version field, as shown below.

    An integration project is structured as a Maven project with multiple sub-modules. The root pom.xml file holds crucial information about the target runtime. The runtime version you configure when you create a new project is saved within the root pom.xml file. The version information is stored in the element under the in the pom.xml file. If there is a need to update the runtime version, you have the flexibility to modify the value to a valid runtime version and ensure that the project runs in the required runtime environment.

    You can establish multiple runtime environments by utilizing updated MI instances. With a valid WSO2 subscription, you can also access and download updates to set up an updated MI server locally. This update process allows you to select a preferred update level as the runtime version. Consequently, you can run your integration on a runtime with the latest updates, ensuring optimal performance and access to new features.

    "},{"location":"develop-components/manage-the-micro-integrator-runtime-version-in-your-integration-project/#configure-a-micro-integrator-runtime-environment-in-integration-studio","title":"Configure a Micro Integrator runtime environment in Integration Studio","text":"

    If you are using WSO2 Integration Studio, follow these steps to set up a remote server instance with a Micro Integrator runtime environment to execute your integration project:

    Note

    If you have not downloaded and installed WSO2 Integration Studio, you can follow the installation instructions in the WSO2 API Manager documentation.

    1. Launch WSO2 Integration Studio and click\u00a0Add Server\u00a0in the\u00a0Getting Started\u00a0view.
    2. In the Define a New Server dialog, click to expand the WSO2 directory and select WSO2 Remote Server.

    3. Enter the WSO2 Micro Integrator Management API URL in the Server URL field and click Test Connection.

      Note

      The Management API of WSO2 Micro Integrator is an internal REST API introduced to substitute MI\u00a0admin services. The default HTTPS port of the Management API of WSO2 Micro Integrator is 9164. If you have not manually changed the default port, you must set the Management API URL as https://localhost:9164/management. If you have changed the default HTTPS port, you must set the port number appropriately when specifying the Server URL. For more information on the default ports of WSO2 Micro Integrator, see WSO2 Micro Integrator default ports in the WSO2 API Manager documentation.

    4. Click Finish.

    5. In the Add and Remove dialog, select the integration components to move from the left side to the right side.
    6. Click Add >.
    7. Click Finish.

    Your integration project is now running in a remote server instance with the Micro Integrator runtime environment you require. If you need to make changes to the integration project, expand the remote server instance, right-click on the deployed exporter project, and select Redeploy to apply the changes.

    "},{"location":"develop-components/manage-the-micro-integrator-runtime-version-in-your-integration-project/#convention-for-version-interpretation-in-choreo-deployments","title":"Convention for version interpretation in Choreo deployments","text":"

    You can use the following convention to indicate the required MI runtime version in your integration project:

    Version format Example Description Product version 4.1.0, 4.2.0 Deploy on the latest update level of the mentioned product version. Product version with update level 4.1.0.15, 4.2.0.17 Deploy on the exact update level of the mentioned product version. GA version 4.1.0.0, 4.2.0.0 Deploy on the exact GA version without any update. Default version Empty value Deploy on the latest update level of the default product version.

    Choreo utilizes Alpine images for configuring and deploying the Micro Integrator runtime. This includes automated configuration of the JRE/JDK, customized to the compatibility of the chosen runtime version, simplifying the setup procedure.

    "},{"location":"develop-components/manage-the-micro-integrator-runtime-version-in-your-integration-project/#migrate-between-runtime-versions","title":"Migrate between runtime versions","text":"

    Changing the runtime version in an integration project may become necessary during product version upgrades or when you want to apply updates.

    To change the runtime version of a MI Integration, follow the below steps.

    "},{"location":"develop-components/manage-the-micro-integrator-runtime-version-in-your-integration-project/#update-the-runtime-version-in-the-integration-project","title":"Update the runtime version in the integration project","text":"

    To change the runtime version in the integration project, follow the steps below: 1. Open the project in Integration Studio. 2. Right-click on the project and select Change Runtime MI Version. 3. Specify the new runtime version as shown below: 4. Alternatively, you can manually update the version by opening the root pom.xml file. Open pom.xml and change the required runtime version in <project.runtime.version> element under <properties> section.

    To test the changes locally, you must download and set up the runtime environment locally. Then, you must configure the Integration Studio runtime environment by directing it to the locally installed MI runtime. Once the setup is complete, you can deploy your integrations on the MI runtime environment and proceed to the testing phase.

    After completing the tests to ensure everything works as expected, you can follow below steps to deploy the project in Choreo:

    1. Commit and push the changes to your repository.
    2. Go to https://console.choreo.dev/ and sign in.
    3. Select your project from the Project list in the header.
    4. Select your MI integration component from the Component list in the header.
    5. In the left navigation menu, click Build.
    6. Select the latest commit and click Build.
    7. In the left navigation menu, click Deploy.
    8. Click on the Configure and Deploy and deploy the component.
    9. Verify the Runtime version by checking the logs by selecting the Runtime Logs under the Observability section.

    You will see the runtime version in the logs as shown below:

    Next, you must conduct additional testing in the development environment on Choreo before you promote the integration to production environments.

    "},{"location":"develop-components/manage-the-micro-integrator-runtime-version-in-your-integration-project/#troubleshoot-errors","title":"Troubleshoot errors","text":"

    The following error codes can help you troubleshoot errors that occur during the integration component build:

    Error code Description 110 - 119 Internal server error. 121 Malformed runtime version. 122 The specified runtime version is not available. Either the product or update level is not available. 123 Trivy security vulnerabilities found in the libs directory. 124 Trivy security vulnerabilities found in the dropins directory. 125 Trivy security vulnerabilities found in the libs or dropins directory. 126 Error building integration project."},{"location":"develop-components/work-with-the-micro-integrator-runtime-in-choreo/","title":"Work with the Micro Integrator Runtime in Choreo","text":"

    WSO2 Micro Integrator (WSO2 MI) is a lightweight, high-performance integration runtime. It allows you to run integrations developed using WSO2 Integration Studio within Choreo.

    The topics on this page walk you through the key aspects you need to understand to use the WSO2 MI runtime effectively in Choreo.

    "},{"location":"develop-components/work-with-the-micro-integrator-runtime-in-choreo/#integration-types","title":"Integration types","text":"

    Choreo supports the following WSO2 MI integrations that cater to different use cases and requirements. Each integration type serves a specific purpose. Therefore, it is essential to understand their differences to easily choose the most appropriate integration for your use case.

    • Service: Exposes an integration as an API via HTTP, making it possible to create a RESTful interface for your integration services. This type is ideal for scenarios where you need to provide an API for external systems or clients to interact with your integration.
    • Event Handler: Triggers an integration based on external events such as messages arriving on a queue or updates in a database. This type is well-suited for implementing event-driven architectures or responding to changes in your system's environment.
    • Scheduled Task: Runs an integration automatically at predefined time intervals, ensuring that specific integration tasks occur at regular intervals. This type is ideal for batch processing, data synchronization, or periodic maintenance tasks.
    • Manual Task: Initiates an integration via user action, giving you full control over when the integration executes. This type is useful for on-demand tasks, testing, or debugging purposes.
    "},{"location":"develop-components/work-with-the-micro-integrator-runtime-in-choreo/#develop-integrations-with-wso2-integration-studio","title":"Develop integrations with WSO2 Integration Studio","text":"

    WSO2 Integration Studio is a powerful, Eclipse-based graphical development environment that enables you to build and deploy integration artifacts in WSO2 Micro Integrator. This comprehensive IDE offers a robust set of tools for designing and testing integration flows and crafting integration artifacts. By utilizing the visual, drag-and-drop capabilities of WSO2 Integration Studio, developers can significantly reduce the time and effort needed to construct and deploy integration flows.

    In addition to streamlining the development process, Integration Studio offers features such as debugging, testing, and version control to ensure the quality and reliability of integration flows. By creating an Integration project and Composite Exporter project in WSO2 Integration Studio, developers can export their integration projects as a single deployment artifact, known as a composite application. This composite application encompasses all the components and configurations necessary for deploying the integration project to WSO2 Micro Integrator.

    The Composite Exporter project simplifies the deployment process by allowing developers to package their integration projects as a single, self-contained artifact that can be easily deployed and managed. This approach enhances the consistency and reliability of integration projects while streamlining the overall deployment process.

    To start developing integrations with WSO2 Integration Studio, see WSO2 API Manager Documentation - Developing Integration Solutions.

    "},{"location":"develop-components/work-with-the-micro-integrator-runtime-in-choreo/#integration-project-directory-structure","title":"Integration project directory structure","text":"

    An Integration Project in WSO2 Integration Studio is a multi-module Maven project that can contain multiple modules with WSO2 Synapse configurations and a composite application module to export all the configurations as a single deployable artifact.

    An integration project directory structure includes the following key components:

    • WSO2 Synapse configurations: These modules contain the essential configurations for the integration project.
    • Composite Application module: This module is responsible for exporting all the Synapse configurations as a single deployable artifact.

    Optionally, you can include the following components in your integration project:

    • OpenAPI definition file: You can add the OpenAPI definition file to any location within the project. When creating a component, you'll need to define the path to this file. Choreo will automatically generate an OpenAPI definition for you based on your integration project, if you don't provide one.
    • Java libraries: If your integration project requires additional Java libraries, you can add them to the libs directory located in the project root.
    • deployment.toml file: This optional configuration file allows you to customize the preconfigured settings of WSO2 MI instances running on Choreo. By including this file, you can tailor the behavior of your WSO2 MI instances to better suit your project's specific requirements.

    Understanding the Integration Project directory structure is crucial for organizing your project and ensuring that all necessary components are included in the final deployable artifact.

    "},{"location":"develop-components/work-with-the-micro-integrator-runtime-in-choreo/#openapi-support","title":"OpenAPI support","text":"

    OpenAPI Support plays a crucial role in enhancing the functionality of integrations exposed as APIs. By providing an OpenAPI definition for your exposed integration, you can streamline testing and management processes, ensuring a more efficient and user-friendly experience. Choreo will automatically generate an OpenAPI definition for you based on your integration project, if you don't provide one, saving you time and effort.

    To incorporate OpenAPI support, store the OpenAPI definition file within the repository hosting your Integration Studio project. When creating the project, simply point to the file's location in the repository. If needed, you can change the location of the OpenAPI definition file later via the deploy page.

    By leveraging OpenAPI Support, you can optimize the way you test and manage your integrations, resulting in a more efficient development process and a smoother user experience.

    "},{"location":"develop-components/work-with-the-micro-integrator-runtime-in-choreo/#work-with-third-party-libraries","title":"Work with third-party libraries","text":"

    The use of third-party libraries in your Micro Integrator project can offer several advantages, such as enhanced functionality, improved integration capabilities, optimized performance, and reduced development time.

    Here are some of the benefits of adding third-party JARs to the Micro Integrator:

    • Increased functionality: Third-party libraries can extend the core Micro Integrator distribution, allowing for greater flexibility and customization of integration solutions.
    • Enhanced integration capabilities: Third-party libraries enable the Micro Integrator to interact with existing systems such as databases or other APIs, improving overall integration capabilities.
    • Optimized performance: By offering optimized implementations of common functions, third-party libraries can improve the performance of the Micro Integrator.
    • Efficient development: Developers can avoid re-implementing commonly used functions, reducing development time and increasing efficiency.

    To incorporate third-party libraries into your Micro Integrator project, create a new directory called libs at the root of your project. If your project root and GitHub repository root are not the same, place the libs directory in the project root. After adding the required JAR files to the libs directory, the Micro Integrator runtime will automatically include them when deploying the component. This process ensures that any dependencies needed by your integration flow are available at runtime.

    In addition to jar libraries, you may also need to incorporate OSGi bundle JARs into your project. To do this, create another directory called dropins at the root of your project. Similarly, if the project root and GitHub repository root differ, place the dropins directory in the project root. Within the dropins directory, add the OSGi bundle JAR files. The OSGI runtime will pick up these bundles during deployment, enabling you to utilize their functionality within your Micro Integrator project.

    "},{"location":"develop-components/work-with-the-micro-integrator-runtime-in-choreo/#importing-custom-certificates-to-mi","title":"Importing custom certificates to MI","text":"

    The feature enables Choreo MI users to import certificates into the MI client-truststore.jks file. This functionality proves valuable when users need to establish connections with servers or services utilizing SSL/TLS encryption and possessing self-signed certificates or certificates issued by private certificate authorities (CAs) that are not automatically trusted. Importing the certificate to the MI client-truststore.jks file enables MI clients to establish secure connections with the server or service seamlessly, eliminating SSL/TLS errors or warnings.

    Before importing the certificate, it is necessary to obtain the certificate file, which can be in PEM or DER format. You can get the certificate from the server or service provider or export it from a web browser. Certificates should be added to the /wso2mi/certs/ folder. Users need to verify that the mount path for the certificate file aligns with this specific path.

    1. In the Choreo console, select the component you wish to add a certificate to.
    2. From the left navigation click Deploy.
    3. Click on the Configs and Secrets tab.
    4. Click Create.
    5. Select ConfigMap as the Config Type and File Mount as the Mount Type.
    6. Click Next.

    7. Specify the following values as mount configurations:

      Field Value Config Name An appropriate name for the certificate. Mount path /wso2mi/certs/<filename>. For example, /wso2mi/certs/certificate.crt

    8. Click Upload File and attach the certificate.

    9. Click Create.
    "},{"location":"develop-components/work-with-the-micro-integrator-runtime-in-choreo/#working-with-sensitive-data-using-mi-secure-vault","title":"Working with sensitive data using MI Secure Vault","text":"

    MI Secure Vault is a feature that allows users to securely store sensitive data, such as passwords and tokens, and provide access to that data to MI Integrations. This feature provides an added layer of security to your integrations by reducing the risk of accidental exposure of sensitive data.

    To use MI Secure Vault to work with sensitive data, follow these steps:

    1. Select the component from the Choreo Console.
    2. From the left navigation, click Deploy.
    3. Click on the Configure and Deploy.
    4. Click on the Add Environment Configurations

    5. Specify the following values as configurations:

      Field Value Name An appropriate name for the secret/alias. Value Value for the secret

    6. Select Mark as a Secret.

    7. Click Add.
    8. Click Deploy.
    9. Once the secret has been created, you can access it in your integration code using the following syntax:

    <property name=\"secret_value_1\" expression=\"wso2:vault-lookup('user_pass')\" scope=\"default\" type=\"STRING\"/>\n
    This code retrieves the secret named \"user_pass\" from the MI Secure Vault and stores it in the property named \" secret_value_1\". You can then use this property in your integration code to access the secret value.

    You can refer to the Accessing secrets section of MI Secure Vault documentation for more information on these features. By using MI Secure Vault to store and access sensitive data in your integrations, you can ensure that your integrations remain secure and protect sensitive data from unauthorized access.

    "},{"location":"develop-components/work-with-the-micro-integrator-runtime-in-choreo/#scan-third-party-libraries-to-identify-security-vulnerabilities","title":"Scan third-party libraries to identify security vulnerabilities","text":"

    Scanning third-party libraries for security vulnerabilities is essential for identifying potential weaknesses in an application that could be exploited by attackers. Taking a proactive approach to security helps organizations detect and mitigate risks before they can be exploited, preventing data breaches, system compromises, and other security incidents.

    Choreo incorporates a security vulnerability scanning process during deployment. It uses Trivy to scan and detect critical vulnerabilities in third-party libraries added to the integration component. If the scan uncovers any critical vulnerabilities, the deployment process is halted. The deployment pane displays the Trivy scan status and any security failures in the Library (Trivy) vulnerable scan step, which can be accessed by clicking on it. Once the vulnerability has been addressed, you can redeploy the component.

    "},{"location":"develop-components/work-with-the-micro-integrator-runtime-in-choreo/#customize-wso2-micro-integrator-preconfigured-settings","title":"Customize WSO2 Micro Integrator preconfigured settings","text":"

    Customizing WSO2 Micro Integrator Preconfigured Settings is essential for ensuring that the integration solution works optimally within the specific context of your organization. While WSO2 MI comes with preconfigured settings designed for general use, these settings may not be suitable for every organization's unique requirements. Customizing these settings can help optimize performance and ensure compatibility with your organization's systems and applications.

    To customize the preconfigured settings of WSO2 MI instances running on Choreo, define a deployment.toml file in the GitHub repository subpath of your Micro Integrator project:

    Note

    If you change critical configuration parameters such as port offset and hostname, it can break internal communication. Therefore, the recommended approach is to update only the necessary configuration parameters.

    Given below is a sample deployment.toml file that can be used to configure the JMS transport. For more information on WSO2 MI configuration parameters, see the MI Config Catalog.

    [[transport.jms.sender]]\nname = \"myQueueSender\"\nparameter.initial_naming_factory = \"org.apache.activemq.jndi.ActiveMQInitialContextFactory\"\nparameter.provider_url = \"$env{JMS_PROVIDER_URL}\"\nparameter.connection_factory_name = \"QueueConnectionFactory\"\nparameter.connection_factory_type = \"queue\"\nparameter.cache_level = \"producer\"\n\n[[transport.jms.listener]]\nname = \"myQueueListener\"\nparameter.initial_naming_factory = \"org.apache.activemq.jndi.ActiveMQInitialContextFactory\"\nparameter.provider_url = \"$env{JMS_PROVIDER_URL}\"\nparameter.connection_factory_name = \"QueueConnectionFactory\"\nparameter.connection_factory_type = \"queue\"\nparameter.cache_level = \"consumer\"\n
    "},{"location":"develop-components/work-with-the-micro-integrator-runtime-in-choreo/#environment-variables","title":"Environment variables","text":"

    Using environment variables is a recommended practice when developing integration artifacts with WSO2 Integration Studio, as it improves configuration management, security, portability, and manageability. By leveraging environment variables, organizations can streamline the management and maintenance of their integrations, ensuring that updates can be implemented quickly and efficiently.

    The component's Deploy page provides a user-friendly interface to manage environment variables across different environments. For information on managing environment variables for complex use cases, see Configurations and secrets.

    Environment variables offer several benefits:

    • Configuration management: They simplify the process of managing and updating configuration settings, making it easier to maintain consistency across different environments.
    • Security: Environment variables help protect sensitive information by storing it securely and separating it from the main codebase.
    • Portability: By using environment variables, you can ensure that your integration artifacts can be easily migrated and deployed across various environments with minimal changes.
    • Manageability: Environment variables offer a centralized way to manage configuration settings, making it easier to update and maintain your integrations over time.

    For a comprehensive list of parameters that can be configured as environment variables, see WSO2 API Manager Documentation - Injecting Parameters - Supported parameters.

    "},{"location":"develop-components/work-with-the-micro-integrator-runtime-in-choreo/#configure-logging","title":"Configure logging","text":"

    Configuring logging is crucial when developing and maintaining a software system, as it can significantly improve efficiency during the development, testing, and maintenance phases of the software development process. Logging captures events and messages that occur during an application's execution, providing valuable insights for troubleshooting and debugging issues.

    With Micro Integrator instances, you can configure and customize logging according to your requirements. Logging configurations can be added to each MI instance's environment, allowing you to fine-tune logging depending on the specific environment or deployment scenario.

    To configure logging in MI instances, follow the steps given below:

    Tip

    You can use environment variables with specific naming conventions.

    1. Start the variable name with logging_level_ followed by the package or class name.
    2. Replace the dot character in the package name with an underscore.

    3. Set the variable value to the required logging level for the corresponding package or class.

      For example, to enable wire logs, change the logging level of the org.apache.synapse.transport.http.wire package to debug.

    To configure logging, set the environment variable as follows:

    1. In the left navigation menu, click Deploy and then click Configs & Secrets.
    2. Click + Create.
    3. Select ConfigMap as the Config Type and Environment Variables as the Mount Type.
    4. Click Next.

    5. Specify the following values as mount configurations:

      Field Value Config Name An appropriate name for the configuration. Name logging_level_org_apache_synapse_transport_http_wire Value debug

    6. Click Create.

    "},{"location":"develop-components/work-with-the-micro-integrator-runtime-in-choreo/#connectors","title":"Connectors","text":"

    WSO2 Micro Integrator (MI) Connectors are prebuilt connectors designed to simplify integration between WSO2 MI and various other systems. They enable seamless connections to databases, message brokers, REST APIs, and more, allowing you to perform actions such as sending messages, executing queries, or retrieving data. These connectors are easy to use, making it straightforward to incorporate them into your WSO2 MI integration flows. Micro Integrator connectors are versatile and can be utilized in various integration scenarios, including data integration, service-oriented architecture (SOA) integration, and event-driven architecture (EDA) integration.

    WSO2 Integration Studio is a comprehensive development environment that facilitates the creation of integration flows using WSO2 Micro Integrator Connectors. With Integration Studio, you can design and implement integration flows that connect diverse systems and execute various actions, such as sending messages, executing queries, or retrieving data. You can build integration flows using either prebuilt connectors provided by WSO2 MI or custom connectors developed using the Connector Development Toolkit. Integration Studio offers a graphical user interface that simplifies the process of building and testing integration flows while also providing a set of tools for managing and deploying these flows in a WSO2 MI runtime environment.

    For more information, see the following topics in the WSO2 API Manager documentation.

    • Connectors Overview
    • Adding Connectors
    "},{"location":"develop-components/work-with-the-micro-integrator-runtime-in-choreo/#deploying-integrations-in-choreo","title":"Deploying integrations in Choreo","text":"

    WSO2 MI buildpack is where you can deploy integrations developed with WSO2 Micro Integrator as an API. In this preset, you have three different ways to define endpoints. Choreo gives priory to the definition of endpoints in the below-mentioned order.

    1. Using endpoints.yaml file This is the most flexible method to define endpoints. You can configure the endpoint details with the endpoints.yaml configuration file. Place this file in the .choreo directory in the project path of the component. If the Micro Integrator project has inbound endpoints, you can expose them via different endpoints using the endpoints.yaml

      See Understanding the endpoints.yaml file to learn about the endpoints.yaml file.

    2. Auto generating endpoints If endpoints.yaml is not provided and if the source Micro Integrator project has APIs, Choreo scans the project and generates the API endpoints. If the project has few APIs, an endpoint will be generated for each API. The visibility of this auto-generated endpoint is set to Public by default. You can change the visibility in the deployment flow.

    3. Provide default endpoints If endpoints.yaml is not provided and if the source Micro Integrator project doesn't have APIs, Choreo generates a default endpoint which will expose the default micro integrator port (8290) with Public visibility and wildcard context.

    "},{"location":"develop-components/work-with-the-micro-integrator-runtime-in-choreo/#explore-choreo-examples-on-github","title":"Explore Choreo examples on GitHub","text":"

    For a hands-on experience with MI-based integrations in Choreo, we recommend exploring our samples in Choreo Console. You can filter out the samples based on the buildpack WSO2 MI. This will point you to the samples in the Choreo samples GitHub repository

    "},{"location":"develop-components/work-with-the-micro-integrator-runtime-in-choreo/#choreo-samples-github-repository","title":"Choreo samples - GitHub Repository","text":"

    • Fork the Repository: Start by forking the repository to your account.

    • Explore & run: Navigate through the different integration scenarios. Each example has a README.md with setup and execution instructions.

    "},{"location":"develop-components/develop-integrations/develop-a-manual-task/","title":"Develop a Manual Task","text":"

    This guide walks you through the steps to develop, deploy, test, and observe a manual task using Choreo.

    In this guide, you will:

    • Develop a manual task to fetch the weather forecast for a specified location for the next 24 hours from the OpenWeatherMap API.
    • Process the weather data to a specific format.
    • Send the formatted data to a specified email address.
    "},{"location":"develop-components/develop-integrations/develop-a-manual-task/#prerequisites","title":"Prerequisites","text":"

    Before you try out the steps in this guide, complete the following:

    • If you are signing in to the Choreo Console for the first time, create an organization as follows:

      1. Go to https://console.choreo.dev/, and sign in.
      2. Enter a unique organization name. For example, Stark Industries.
      3. Read and accept the privacy policy and terms of use.
      4. Click Create. This creates the organization and opens the Project Home page of the default project created for you.

    • Fork the Choreo samples repository, which contains the sample integration for this guide.

      Repository file structure

      To work with the sample repository, it is important to familiarize yourself with the repository file structure. The sample code for this guide is in the <sample-repository-dir>/weather-to-email-integration directory. To understand how the functionality is implemented, you must read the code comments. The following table describes what you will find in each file in the repository:

      File path File content Ballerina.toml Contains metadata about the project Dependencies.toml Lists the dependencies required for the project main.bal Contains the entry point of the project, including the main function types.bal Contains custom data types used in the project utils.bal Contains utility functions and helper functions used in the project

    • Go to OpenWeatherMap and sign up to obtain an API key. For details on how to obtain an API key, see the OpenWeatherMap documentation.

    "},{"location":"develop-components/develop-integrations/develop-a-manual-task/#step-1-create-a-manual-task-component","title":"Step 1: Create a manual task component","text":"
    1. Go to https://console.choreo.dev/ and sign in. This opens the project home page.
    2. If you already have one or more components in your project, click + Create. Otherwise, proceed to the next step.
    3. Click the Manual Task card.

    4. Enter a unique name and a description for the component. You can use the name and description given below:

      Field Value Component Name WeatherToEmail Description My first manual task

    5. Go to the GitHub tab.

    6. To allow Choreo to connect to your GitHub account, click Authorize with GitHub. If you have not already connected your GitHub repository to Choreo, enter your GitHub credentials and select the repository you created in the prerequisites section to install the Choreo GitHub App.

      Alternatively, you can paste the Choreo samples repository URL in the Provide Repository URL field to connect to it without requiring authorization from the Choreo Apps GitHub application. However, authorizing the repository with the Choreo GitHub App is necessary if you want to enable Auto Deploy for the component.

      Note

      The Choreo GitHub App requires the following permissions:

      • Read and write access to code and pull requests.
      • Read access to issues and metadata.

      You can revoke access if you do not want Choreo to have access to your GitHub account. However, write access is exclusively utilized for sending pull requests to a user repository. Choreo will not directly push any changes to a repository.

    7. Enter the following information:

      Field Description Organization Your GitHub account Repository choreo-samples Branch main Buildpack Ballerina Project Directory weather-to-email-integration

      Tip

      • Buildpack specifies the type of build to run depending on the implementation of the component. It converts the integration code into a Docker image that can run on Choreo cloud. If an integration is developed using WSO2 Integration Studio, select Micro Integrator as the buildpack. If an integration is developed using the Ballerina language, select Ballerina as the buildpack.

      • Project Directory specifies the location of the project to build the component.

    8. Click Create. Choreo initializes the component with the sample implementation and opens the Overview page of the component.

    "},{"location":"develop-components/develop-integrations/develop-a-manual-task/#step-2-build-the-manual-task","title":"Step 2: Build the manual task","text":"

    To build the manual task, follow the steps given below:

    1. In the left navigation menu, click Build.
    2. In the Builds pane, click Build. This opens the Commits pane where you can see all the commits related to the component.

    3. Select the latest commit and click Build. This triggers the build process and displays the build progress in the Build Logs pane.

      Info

      The build process can take a while to complete. When the build process is complete, the build will be listed in the Builds pane along with the build status.

    Here, you will see the build status as Success.

    "},{"location":"develop-components/develop-integrations/develop-a-manual-task/#step-3-deploy-the-manual-task","title":"Step 3: Deploy the manual task","text":"

    To deploy the manual task, follow the steps given below:

    1. In the left navigation menu, click Deploy.
    2. In the Set Up card, click Configure & Deploy.

    3. In the Configurations pane, specify values as follows for the configurable variables:

      Tip

      The configurable variables populated here are defined in the sample Ballerina project used in this guide. To learn how to declare configurable variables in Ballerina, see the Ballerina documentation on declaring configurable variables. If configurable variables are detected in a connected Ballerina project, Choreo prompts for the respective values during component deployment.

      Field Value apiKey The API key you obtained in the prerequisites section latitude Latitude of the location to get the weather forecast longitude Longitude of the location to get the weather forecast email The email address to receive the formatted weather forecast information

      Note

      If you use Ballerina as the buildpack and you want to set a configurable variable as a secret, click the lock icon corresponding to the configurable variable. This marks it as a secret and conceals the input value.

      For example, if you consider the configurable variables in this guide and set the apiKey as a secret, its input value will be concealed as follows:

      If you want to update the input value at a later time, you can click Update Secret Content and specify a new value.

    4. Click Deploy.

    "},{"location":"develop-components/develop-integrations/develop-a-manual-task/#step-4-execute-the-manual-task","title":"Step 4: Execute the manual task","text":"

    To execute the manual task, follow the steps given below:

    1. In the left navigation menu, click Execute.

    2. Click Run Now. This triggers the task.

      Inject dynamic values into your application as command-line arguments

      If you want to inject dynamic values into your application as command-line arguments when you run a manual task, follow the steps given below:

      1. Click the drop-down icon next to Run Now and then click Run with Arguments.
      2. In the Runtime Arguments pane that opens, enter the arguments you want to pass to your application.
      3. Click Execute. This triggers the task with the specified arguments.

      The capability to run a manual task with arguments is supported for the following buildpacks:

      DockerfileGoJavaNodeJSWSO2 MIBallerina

      To explore a Dockerfile-based manual task with arguments, try out the Hello World Task sample. For instructions, see the readme.md file in the sample repository.

      Info

      When you work on Docker projects, the Run with Arguments capability is not supported if the Dockerfile contains CMD. In such scenarios, you must use ENTRYPOINT to define your default commands.

      To explore a Go-based manual task with arguments, try out the Hello World Go Task sample. For instructions, see the readme.md file in the sample repository.

      To explore a Java-based manual task with arguments, try out the Hello World Java Task sample. For instructions, see the readme.md file in the sample repository.

      Info

      When you work on Java projects:

      • The Run with Arguments capability is not supported if Procfile is available in the project.
      • The Main class should be defined in the manifest file.
      • If Maven files such as mvn.cmd exist in the project without the .mvn directory, the build will fail. To ensure a successful build, you must either commit the .mvn directory along with any Maven files or not include any Maven files in the project if you choose not to commit the .mvn directory.

      To explore a NodeJS-based manual task with arguments, try out the Hello World NodeJS Task sample. For instructions, see the readme.md file in the sample repository.

      Info

      When you work on NodeJS projects:

      • The Run with Arguments capability is not supported if Procfile is available in the project.
      • The project root must contain the package.json file with the main attribute defined.

      To explore a WSO2 MI-based manual task with arguments, try out the Weather to Logs Task sample. For instructions, see the readme.md file in the sample repository.

      Info

      When you work on WSO2 MI projects and you want to deploy a WSO2 MI integration as a manual task in Choroeo, you must use the WSO2 MI automation mode. For details, see Running the Micro Integrator in Automation Mode.

      To explore a Ballerina manual task with arguments, try out the Weather to Email Task sample. For instructions, see the README.md file in the sample repository.

      Info

      If you want to pass arguments to Ballerina main functions, you can use the Run with Arguments capability. For details on the arguments you can pass, see the Ballerina documentation. You can also override configurable values in the same manner. For more information, see Provide values to configurable variables.

    "},{"location":"develop-components/develop-integrations/develop-a-manual-task/#step-5-test-the-manual-task","title":"Step 5: Test the manual task","text":"

    Once the task is triggered, an email with the subject [WSO2 Choreo Demo] Next 24H Weather Forecast is sent from choreo.demo@gmail.com to the email address specified as the email configurable variable value in Step 3.

    If the manual task ran successfully, you should receive an email similar to the following to the email address you specified:

    "},{"location":"develop-components/develop-integrations/develop-a-manual-task/#step-6-observe-the-manual-task","title":"Step 6: Observe the manual task","text":"

    The observability view in Choreo displays graphs that depict details such as throughput, latency, diagnostic data, and logs to identify and troubleshoot anomalies in components you deploy.

    To visualize and monitor the performance of the manual task you deployed, click Observability in the left navigation menu. You can observe the following:

    • The throughput and latencies of requests served over a given period.
    • The logs that are generated over a given period.
    • The flame graph (Diagnostics View) that is generated over a given period.
    • The low-code diagram.

    To learn more about the observability details you can view via Choreo observability, see Observability Overview.

    "},{"location":"develop-components/develop-integrations/develop-a-manual-task/#step-7-monitor-executions","title":"Step 7: Monitor executions","text":"

    To track and monitor executions associated with the deployed scheduled task, go to the left navigation menu and click Execute.

    Tip

    The Execute view is applicable to both scheduled and manual tasks.

    You can view the following information:

    • The total number of executions within the past 30 days.

    • The currently active executions and those that are already complete.

      Here, you can view information such as the execution ID, the revision of the execution, and the time it was triggered.

    • Detailed execution logs for a specific execution.

      You can click on an execution to view detailed logs related to it.

      Info

      It may take a few minutes for the logs to appear. You may need to manually refresh to view the latest logs.

    "},{"location":"develop-components/develop-integrations/develop-a-scheduled-task/","title":"Develop a Scheduled Task","text":"

    Choreo is a versatile integration platform that allows you to create various types of integrations depending on your requirement.

    If you have a requirement to automatically run a specific integration at regular intervals, you can use Choreo to develop a scheduled task. This type of integration can automate the synchronization of data between different systems at specified intervals, reducing errors and improving productivity by eliminating the need for manual intervention.

    This guide walks you through the steps to develop, deploy, test, and observe a scheduled task using Choreo.

    In this guide, you will:

    • Develop a scheduled task to fetch the weather forecast for a specified location for the next 24 hours from the OpenWeatherMap API.
    • Process the weather data to a specific format.
    • Send the formatted data to a specified email address at a specific time every day.
    "},{"location":"develop-components/develop-integrations/develop-a-scheduled-task/#prerequisites","title":"Prerequisites","text":"

    Before you try out the steps in this guide, complete the following:

    • If you are signing in to the Choreo Console for the first time, create an organization as follows:

      1. Go to https://console.choreo.dev/, and sign in using your preferred method.
      2. Enter a unique organization name. For example, Stark Industries.
      3. Read and accept the privacy policy and terms of use.
      4. Click Create. This creates the organization and opens the Project Home page of the default project created for you.

    • Fork the Choreo samples repository, which contains the sample integration for this guide.

      Repository file structure

      To work with the sample repository, it is important to familiarize yourself with the repository file structure. The sample code for this guide is in the <sample-repository-dir>/weather-to-email-scheduled-task directory. To understand how the functionality is implemented, you must read the code comments. The following table describes what you will find in each file in the repository:

      File path File content Ballerina.toml Contains metadata about the project Dependencies.toml Lists the dependencies required for the project main.bal Contains the entry point of the project, including the main function types.bal Contains custom data types used in the project utils.bal Contains utility functions and helper functions used in the project

    • Go to OpenWeatherMap and sign up to obtain an API key. For details on how to obtain an API key, see the OpenWeatherMap documentation.

    "},{"location":"develop-components/develop-integrations/develop-a-scheduled-task/#step-1-create-a-scheduled-task-component","title":"Step 1: Create a scheduled task component","text":"
    1. Go to https://console.choreo.dev/ and sign in. This opens the project home page.
    2. If you already have one or more components in your project, click + Create. Otherwise, proceed to the next step.
    3. Click the Scheduled Task card.

    4. Enter a unique name and a description for the component. You can use the name and description given below:

      Field Value Component Name WeatherToEmail Description My first scheduled task

    5. Go to the GitHub tab.

    6. To allow Choreo to connect to your GitHub account, click Authorize with GitHub. If you have not already connected your GitHub repository to Choreo, enter your GitHub credentials and select the repository you created in the prerequisites section to install the Choreo GitHub App.

      Alternatively, you can paste the Choreo samples repository URL in the Provide Repository URL field to connect to it without requiring authorization from the Choreo Apps GitHub application. However, authorizing the repository with the Choreo GitHub App is necessary if you want to enable Auto Deploy for the component.

      Note

      The Choreo GitHub App requires the following permissions:

      • Read and write access to code and pull requests.
      • Read access to issues and metadata.

      You can revoke access if you do not want Choreo to have access to your GitHub account. However, write access is exclusively utilized for sending pull requests to a user repository. Choreo will not directly push any changes to a repository.

    7. Enter the following information:

      Field Description Organization Your GitHub account Repository choreo-samples Branch main Buildpack Ballerina Project Directory weather-to-email-scheduled-task

      Tip

      • Buildpack specifies the type of build to run depending on the implementation of the component. It converts the integration code into a Docker image that can run on Choreo cloud. If an integration is developed using WSO2 Integration Studio, select Micro Integrator as the buildpack. If an integration is developed using the Ballerina language, select Ballerina as the buildpack.

      • Project Directory specifies the location of the project to build the component.

    8. Click Create. Choreo initializes the component with the sample implementation and opens the Overview page of the component.

    Now you can proceed to build and deploy the scheduled task.

    "},{"location":"develop-components/develop-integrations/develop-a-scheduled-task/#step-2-build-the-scheduled-task","title":"Step 2: Build the scheduled task","text":"

    To build the scheduled task, follow the steps given below:

    1. In the left navigation menu, click Build.
    2. In the Builds pane, click Build. This opens the Commits pane where you can see all the commits related to the component.

    3. Select the latest commit and click Build. This triggers the build process and displays the build progress in the Build Logs pane.

      Info

      The build process can take a while to complete. When the build process is complete, the build will be listed in the Builds pane along with the build status.

    Here, you will see the build status as Success.

    "},{"location":"develop-components/develop-integrations/develop-a-scheduled-task/#step-3-deploy-the-scheduled-task","title":"Step 3: Deploy the scheduled task","text":"

    To deploy the scheduled task, follow the steps given below:

    1. In the left navigation menu, click Deploy.
    2. In the Set Up card, click Configure & Deploy.

    3. In the Configurations pane, specify values as follows for the configurable variables:

      Tip

      The configurable variables populated here are defined in the sample Ballerina project used in this guide. To learn how to declare configurable variables in Ballerina, see the Ballerina documentation on declaring configurable variables. If configurable variables are detected in a connected Ballerina project, Choreo prompts for the respective values during component deployment.

      Field Value apiKey The API key you obtained in the prerequisites section latitude Latitude of the location to get the weather forecast longitude Longitude of the location to get the weather forecast email The email address to receive the formatted weather forecast information

      Note

      If you use Ballerina as the buildpack and you want to set a configurable variable as a secret, click the lock icon corresponding to the configurable variable. This marks it as a secret and conceals the input value.

      For example, if you consider the configurable variables in this guide and set the apiKey as a secret, its input value will be concealed as follows:

      If you want to update the input value at a later time, you can click Update Secret Content and specify a new value.

    4. Click Next.

    5. In this step, you must define a schedule to run the task. In this guide, you set the schedule to receive the weather information daily at 8.00 AM UTC. Enter values as follows to configure the schedule:

      Field Value Select Time Zone Select a time zone to schedule the task Select Range Day Every 1 At 08:00

      Tip

      When you develop a scheduled task, you can define a schedule depending on your requirement. If you want to test and verify the immediately, you can schedule the deployment to run in just a few minutes after you create it. However, to avoid unnecessary expenses, make sure you reschedule or stop the deployment once you test and verify.

    6. Click Deploy. This deploys the scheduled task to the development environment and indicates the Scheduled Status as Active in the Development card.

    You can test the scheduled task when it runs at the configured time.

    "},{"location":"develop-components/develop-integrations/develop-a-scheduled-task/#step-4-test-the-scheduled-task","title":"Step 4: Test the scheduled task","text":"

    When the scheduled task runs at the configured time, an email with the subject [WSO2 Choreo Demo] Next 24H Weather Forecast is sent from choreo.demo@gmail.com to the email address specified as the email configurable variable value in Step 3.

    If the scheduled task ran successfully, you should receive an email similar to the following to the email address you specified:

    "},{"location":"develop-components/develop-integrations/develop-a-scheduled-task/#step-5-observe-the-scheduled-task","title":"Step 5: Observe the scheduled task","text":"

    The observability view in Choreo displays graphs that depict details such as throughput, latency, diagnostic data, and logs to identify and troubleshoot anomalies in components you deploy.

    To visualize and monitor the performance of the scheduled task you deployed, click Observability in the left navigation menu. You can observe the following:

    • The throughput and latencies of requests served over a given period.
    • The logs that are generated over a given period.
    • The flame graph (Diagnostics View) that is generated over a given period.
    • The low-code diagram.

    To learn more about the observability details you can view via Choreo observability, see Observability Overview.

    "},{"location":"develop-components/develop-integrations/develop-a-scheduled-task/#step-6-monitor-executions","title":"Step 6: Monitor executions","text":"

    To track and monitor executions associated with the deployed scheduled task, go to the left navigation menu and click Execute.

    Tip

    The Execute view is applicable to both scheduled and manual tasks.

    You can view the following information:

    • The total number of executions within the past 30 days.

    • The currently active executions and those that are already complete.

      Here, you can view information such as the execution ID, the revision of the execution, and the time it was triggered.

    • Detailed execution logs for a specific execution.

      You can click on an execution to view detailed logs related to it.

      Info

      It may take a few minutes for the logs to appear. You may need to manually refresh to view the latest logs.

    "},{"location":"develop-components/develop-integrations/develop-an-event-handler/","title":"Develop an Event Handler","text":"

    An Event Handler executes predefined actions in response to specific events. Choreo simplifies the process of creating and deploying such integrations.

    This guide walks you through the steps to create and deploy an Event Handler using WSO2 MI and Choreo.

    In this guide, you will build a simple event handler that monitors RabbitMQ for new messages and displays them once they become available.

    "},{"location":"develop-components/develop-integrations/develop-an-event-handler/#prerequisites","title":"Prerequisites","text":"

    Before you try out the steps in this guide, complete the following:

    • If you are signing in to the Choreo Console for the first time, create an organization as follows:

      1. Go to https://console.choreo.dev/, and sign in using your preferred method.
      2. Enter a unique organization name. For example, Stark Industries.
      3. Read and accept the privacy policy and terms of use.
      4. Click Create. This creates the organization and opens the Project Home page of the default project created for you.

    • Use an existing RabbitMQ instance or start a new RabbitMQ instance on a server that can be accessed via the internet. Obtain the username, hostname, password, and vhost from the RabbitMQ instance to use later as environment variables.

    • Fork the Choreo samples repository, which contains the sample integration for this guide.

    "},{"location":"develop-components/develop-integrations/develop-an-event-handler/#step-1-create-an-event-handler-component","title":"Step 1: Create an event handler component","text":"
    1. Go to https://console.choreo.dev/ and sign in. This opens the project home page.
    2. If you already have one or more components in your project, click + Create. Otherwise, proceed to the next step.
    3. Click the Event Handler card.

    4. Enter a unique name and a description for the component. You can use the name and description given below:

      Field Value Component Name SalesOrderListener Description RabbitMQ integration

    5. Go to the GitHub tab.

    6. To allow Choreo to connect to your GitHub account, click Authorize with GitHub. If you have not already connected your GitHub repository to Choreo, enter your GitHub credentials and select the repository you created in the prerequisites section to install the Choreo GitHub App.

      Alternatively, you can paste the Choreo samples repository URL in the Provide Repository URL field to connect to it without requiring authorization from the Choreo Apps GitHub application. However, authorizing the repository with the Choreo GitHub App is necessary if you want to enable Auto Deploy for the component.

      Note

      The Choreo GitHub App requires the following permissions:

      • Read and write access to code and pull requests.
      • Read access to issues and metadata.

      You can revoke access if you do not want Choreo to have access to your GitHub account. However, write access is exclusively utilized for sending pull requests to a user repository. Choreo will not directly push any changes to a repository.

    7. Enter the following information:

      Field Description Organization Your GitHub account Repository choreo-samples Branch main Buildpack WSO2 MI because you are creating the REST API from a WSO2 Integration Studio project Project Directory mi-rabbitmq-listener

      Tip

      • Buildpack specifies the type of build to run depending on the implementation of the component. It converts the integration code into a Docker image that can run on Choreo cloud. If an integration is developed using WSO2 Integration Studio, select Micro Integrator as the buildpack. If an integration is developed using the Ballerina language, select Ballerina as the buildpack.

      • Project Directory specifies the location of the project to build the component.

    8. Click Create.

    "},{"location":"develop-components/develop-integrations/develop-an-event-handler/#step-2-deploy-the-integration","title":"Step 2: Deploy the integration","text":"

    To deploy the integration, follow the steps given below:

    1. In the left navigation menu, click Deploy.
    2. In the Build Area card, click Configure & Deploy.

    3. In the Configurations pane, click + Add corresponding to Environment Variables and add the following environment variables:

      Tip

      Use the values from your RabbitMQ instance as per the Prerequisites section, for the environment variables.

      Name Value HOSTNAME Hostname of your RabbitMQ server VHOST Virtual hostname of your RabbitMQ server USERNAME Username for connecting to RabbitMQ PASSWORD Password associated with the RabbitMQ username

    4. Click Deploy. This deploys the event handler to the development environment and indicates the Deployment Status as Active in the Development card.

    "},{"location":"develop-components/develop-integrations/develop-an-event-handler/#step-3-test-the-integration","title":"Step 3: Test the integration","text":"

    To test the integration, follow the steps given below:

    1. Send a sales order message to the SalesOrderQueue on the RabbitMQ server.
      • You can send a sample sales order message similar to the following: 
        {\n\"order_id\": \"12345\",\n\"customer_name\": \"John Doe\",\n\"product\": \"Widget\",\n\"quantity\": 10,\n\"total_amount\": 100.00\n}\n
    2. Observe the logs:
      • In the left navigation menu, click Logs and then click Runtime Logs. You will see the order message in the logs.

    Now you have gained hands-on experience in creating, configuring, and deploying an event handler.

    "},{"location":"develop-components/develop-integrations/develop-an-integration-with-integration-studio/","title":"Develop an Integration with Integration Studio","text":"

    The seamless integration of APIs, microservices, applications, and data across different languages and formats requires the ability to expose integrations as APIs. Choreo simplifies building, deploying, and managing integration components, making it easy for you to quickly expose integrations as APIs.

    Note

    • To develop integrations that you need to use in Manual Task and Schedule Task components in Choreo, you need to use the automation mode in the WSO2 Micro Integrator. See Running MI in Automation Mode.
    • To develop integrations for any other component types (Service, webhook, event-handler, etc) you need to use the server mode.

    This guide walks you through the steps to expose an integration you created in WSO2 Integration Studio as an API in Choreo.

    In this guide, you will:

    • Create a component to expose the sample integration in the Choreo samples repository as an API.
    • Deploy, test, and observe the integration component.
    • Publish the integration component as an API to the Choreo Developer Portal.
    "},{"location":"develop-components/develop-integrations/develop-an-integration-with-integration-studio/#prerequisites","title":"Prerequisites","text":"

    Before you try out the steps in this guide, complete the following:

    • If you are signing in to the Choreo Console for the first time, create an organization as follows:

      1. Go to https://console.choreo.dev/, and sign in using your preferred method.
      2. Enter a unique organization name. For example, Stark Industries.
      3. Read and accept the privacy policy and terms of use.
      4. Click Create. This creates the organization and opens the Project Home page of the default project created for you.

    • Fork the Choreo samples repository, which contains the sample integration for this guide.

    "},{"location":"develop-components/develop-integrations/develop-an-integration-with-integration-studio/#step-1-create-the-integration-component","title":"Step 1: Create the integration component","text":"
    1. Go to https://console.choreo.dev/ and sign in. This opens the project home page.
    2. If you already have one or more components in your project, click + Create. Otherwise, proceed to the next step.
    3. Click the Service card.

    4. Enter a unique name and a description for the component. You can enter the name and description given below:

      Field Value Component Name Hello World Description Hello World REST API

    5. Go to the GitHub tab.

    6. To allow Choreo to connect to your GitHub account, click Authorize with GitHub. If you have not already connected your GitHub repository to Choreo, enter your GitHub credentials and select the repository you created in the prerequisites section to install the Choreo GitHub App.

      Alternatively, you can paste the Choreo samples repository URL in the Provide Repository URL field to connect to it without requiring authorization from the Choreo Apps GitHub application. However, authorizing the repository with the Choreo GitHub App is necessary if you want to enable Auto Deploy for the component.

      Note

      The Choreo GitHub App requires the following permissions:

      • Read and write access to code and pull requests.
      • Read access to issues and metadata.

      You can revoke access if you do not want Choreo to have access to your GitHub account. However, write access is exclusively utilized for sending pull requests to a user repository. Choreo will not directly push any changes to a repository.

    7. Enter the following information:

      Field Description Organization Your GitHub account Repository choreo-samples Branch main Buildpack WSO2 MI because you are creating the REST API from a WSO2 Integration Studio project Project Directory hello-world-mi

    8. Click Create. Choreo initializes the component with the sample integration.

    "},{"location":"develop-components/develop-integrations/develop-an-integration-with-integration-studio/#step-2-deploy-the-integration-component","title":"Step 2: Deploy the integration component","text":"

    To deploy the integration component to the development environment, follow the steps given below:

    1. In the Choreo Console left navigation menu, click Deploy.
    2. In the Build Area card, click Configure & Deploy.
    3. In the Configurations pane, click Next. This displays details of the endpoint ready to be deployed.

    4. Click Deploy. This deploys the integration component to the development environment. The Development card indicates the Deployment Status as Active when the integration is successfully deployed.

      Tip

      Choreo uses endpoints to expose Service component to the network. You can read more about configuring endpoints in Configure Endoints.

      Tip

      Automatic deployment is enabled for the component by default. Therefore, you are required to perform only the first deployment manually.

    Now you can test the integration.

    "},{"location":"develop-components/develop-integrations/develop-an-integration-with-integration-studio/#step-3-test-the-integration","title":"Step 3: Test the integration","text":"

    To test the integration using the OpenAPI Console. Follow the steps given below:

    1. In the Choreo Console left navigation menu, click Test and then click Console.
    2. In the OpenAPI Console that opens, select Development from the environment drop-down list.
    3. Click to expand the GET /integration operation.
    4. Click Try it out and then click Execute. This sends a request to your deployed integration.

    5. Go to the Response body section and observe the response returned by the integration. If the integration works as expected, you should see a response similar to the following:

      {\"Hello\" : \"Integration\"}

    "},{"location":"develop-components/develop-integrations/develop-an-integration-with-integration-studio/#step-4-observe-the-integration","title":"Step 4: Observe the integration","text":"

    The observability view in Choreo displays graphs that depict details such as throughput, latency, diagnostic data, and logs to identify and troubleshoot anomalies in components you deploy.

    To visualize and monitor the performance of the integration component you deployed, click Observability in the left navigation menu. You can observe the following:

    • The throughput and latencies of requests served over a given period.
    • The logs that are generated over a given period.
    • The flame graph (Diagnostics View) that is generated over a given period.

    To learn more about the observability details you can view via Choreo observability, see Observability Overview.

    "},{"location":"develop-components/develop-integrations/develop-an-integration-with-integration-studio/#step-5-publish-the-integration-component","title":"Step 5: Publish the integration component","text":"

    To publish the integration component, follow the steps given below:

    1. In the Choreo Console left navigation menu, click Manage and then click Lifecycle. This opens the Lifecycle Management pane, where you can see the different lifecycle stages that an API can be in. You can see that the current lifecycle stage is Created.
    2. In the Lifecycle Management pane, click Publish. This changes the API lifecycle stage to Published and exposes the integration as an API in the Choreo Developer Portal.

    To open the published API in the Developer Portal via the Lifecycle Management pane, click Go to Devportal. In the Choreo Developer Portal, you can view the published API, manage subscriptions for it, and generate access tokens for testing purposes.

    Now, you have gained hands-on experience in exposing an integration designed using WSO2 Integration Studio as a REST API in Choreo.

    "},{"location":"develop-components/develop-services/develop-a-ballerina-service/","title":"Develop a Ballerina Service","text":"

    Choreo allows you to develop and deploy applications using your preferred programming language. This guide demonstrates how to deploy a service component that exposes a REST API using the Ballerina language. No prior knowledge of the Ballerina language is required to follow this guide.

    A REST API is a web service adhering to Representational State Transfer (REST) principles, using HTTP methods to access and manage resources. This guide walks you through building a Ballerina service component, deploying it on Choreo, and using it with an HTTP client application.

    In this guide, you will:

    • Build a simple greeting service using a sample service implementation. The sample implementation will have a single resource named greet that accepts a single query parameter as input.

      • Request:

        $ curl GET http://localhost:9090/greeter/greet?name=Ballerina

      • Response:

        $ hello Ballerina!

    • Deploy the service in Choreo. The service will run on port 9090.

    • Test the service.
    "},{"location":"develop-components/develop-services/develop-a-ballerina-service/#prerequisites","title":"Prerequisites","text":"

    Before you try out this guide, complete the following:

    • If you are signing in to the Choreo Console for the first time, create an organization as follows:

      1. Go to https://console.choreo.dev/, and sign in using your preferred method.
      2. Enter a unique organization name. For example, Stark Industries.
      3. Read and accept the privacy policy and terms of use.
      4. Click Create.

      This creates the organization and opens the Project Home page of the default project created for you.

    • Fork the Choreo samples repository, which contains the sample greetings service implementation in Ballerina.

    "},{"location":"develop-components/develop-services/develop-a-ballerina-service/#learn-the-repository-file-structure","title":"Learn the repository file structure","text":"

    It is important to understand the purpose of the key files in the sample service. The following table provides a brief overview of each file in the greeter service:

    Note

    The specified file paths are relative to <sample-repository-dir>/greeting-service.

    Filepath Description service.bal The greetings service code written in the Ballerina language. tests/service_test.bal Test files related to the service.bal file. Ballerina.toml The Ballerina configuration file.

    Let's get started!

    "},{"location":"develop-components/develop-services/develop-a-ballerina-service/#step-1-create-a-service-component","title":"Step 1: Create a service component","text":"

    To create a Ballerina service component, follow these steps:

    1. Go to https://console.choreo.dev/ and sign in. This opens the project home page.
    2. If you already have one or more components in your project, click + Create. Otherwise, proceed to the next step.
    3. Click the Service card.

    4. Enter a display name, a unique name, and a description for the service component. You can enter the values given below:

      Info

      In the Component Name field, you must specify a name to uniquely identify the component in various contexts. The value is editable only at the time you create the component. You cannot change the name after you create the component.

      Field Value Component Display Name Ballerina Greetings Component Name ballerina-greetings Description Send greetings

    5. Go to the GitHub tab.

    6. To allow Choreo to connect to your GitHub account, click Authorize with GitHub. If you have not already connected your GitHub repository to Choreo, enter your GitHub credentials and select the repository you created in the prerequisites section to install the Choreo GitHub App.

      Alternatively, you can paste the Choreo samples repository URL in the Provide Repository URL field to connect to it without requiring authorization from the Choreo Apps GitHub application. However, authorizing the repository with the Choreo GitHub App is necessary if you want to enable Auto Deploy for the component.

      Note

      The Choreo GitHub App requires the following permissions:

      • Read and write access to code and pull requests.
      • Read access to issues and metadata.

      You can revoke access if you do not want Choreo to have access to your GitHub account. However, write access is exclusively utilized for sending pull requests to a user repository. Choreo will not directly push any changes to a repository.

    7. Under Connect Your Repository, enter the following information:

      Field Value Organization Your GitHub account Repository choreo-samples Branch main

    8. Select Ballerina as the buildpack.

    9. In the Ballerina Project Directory, specify /greeting-service.
    10. Click Create. This creates the component and takes you to the Overview page of the component.

    You have successfully created a service that exposes a REST API written in the Ballerina language. Next, let's build and deploy the service.

    "},{"location":"develop-components/develop-services/develop-a-ballerina-service/#step-2-build-and-deploy","title":"Step 2: Build and deploy","text":"

    Now that you have connected the source repository and configured the endpoint details, it's time to build and deploy the service.

    Note

    If you are rebuilding the Ballerina service component after changing the Ballerina version, ensure that before building the code, the version of the Ballerina distribution mentioned in the Ballerina.toml file matches the distribution version specified in the Dependencies.toml file.

    "},{"location":"develop-components/develop-services/develop-a-ballerina-service/#step-21-build","title":"Step 2.1: Build","text":"

    To build the service, follow these steps:

    1. In the left navigation menu, click Build.

    2. On the Build page, click Build Latest.

      Note

      Building the service component may take a while. You can track the progress via the logs in the Build Details pane. Once the build process is complete, the build status changes to Success.

    "},{"location":"develop-components/develop-services/develop-a-ballerina-service/#step-22-deploy","title":"Step 2.2: Deploy","text":"

    To deploy the service, follow these steps:

    1. In the left navigation menu, click Deploy.
    2. On the Set Up card, click Configure & Deploy.
    3. In the Configurations pane that opens, click Next to skip the configuration.

    4. Review the Endpoint Details and click Deploy.

      Note

      Deploying the service component may take a while. Once deployed, the Development environment card indicates the Deployment Status as Active.

      To build and deploy the service, follow the steps below:

    Once you have successfully deployed your service, you can test, manage, and observe it like any other component type in Choreo.

    For detailed instructions, see the following sections:

    • Step 3: Test
    • Step 4: Manage
    "},{"location":"develop-components/develop-services/develop-a-ballerina-service/#manage-the-deployment","title":"Manage the deployment","text":"

    If you want to view Kubernetes-level insights to perform a more detailed diagnosis of this Ballerina REST API, see Choreo's DevOps capabilities.

    "},{"location":"develop-components/develop-services/develop-a-service-with-docker/","title":"Develop a Service with Docker","text":"

    Choreo is a platform that allows you to create and deploy applications in any language.

    In this guide, you will:

    • create a containerized service component using a sample service implementation. The sample implementation will have a single resource named greet that accepts a single query parameter as input.
    • Deploy it in Choreo using a Dockerfile. The service will run on port 9090.
    • Test the service.

    If you want to create a service component that exposes a Ballerina service, see Develop a Ballerina Service .

    "},{"location":"develop-components/develop-services/develop-a-service-with-docker/#prerequisites","title":"Prerequisites","text":"

    Before you try out this guide, complete the following:

    • If you are signing in to the Choreo Console for the first time, create an organization as follows:

      1. Go to https://console.choreo.dev/, and sign in using your preferred method.
      2. Enter a unique organization name. For example, Stark Industries.
      3. Read and accept the privacy policy and terms of use.
      4. Click Create.

      This creates the organization and opens the Project Home page of the default project created for you.

    • Fork the Choreo samples repository, which contains the sample greetings service implementation with the Dockerfile.

    "},{"location":"develop-components/develop-services/develop-a-service-with-docker/#learn-the-repository-file-structure","title":"Learn the repository file structure","text":"

    It is important to understand the purpose of the key files in the sample service. The following table provides a brief overview of each file in the greeter service:

    Note

    The specified file paths are relative to <sample-repository-dir>/greeting-service-go

    Filepath Description main.go The Go-based greeter service code. Dockerfile The Dockerfile to build the container image of the application. .choreo/endpoints.yaml Choreo-specific configuration that provides information about how Choreo exposes the service. openapi.yaml The OpenAPI contract of the greeter service. This is required to publish the service as a managed API. This openapi.yaml file is referenced by the .choreo/endpoints.yaml file.

    Let's get started!

    "},{"location":"develop-components/develop-services/develop-a-service-with-docker/#configure-the-service-port-with-endpoints","title":"Configure the service port with endpoints","text":"

    In Choreo, you can expose your services via endpoints.

    You are going to run the greeter service on port 9090. To securely expose the service through Choreo, you must provide the port and other required information to Choreo. For detailed information on each attribute of an endpoint, see Configure Endpoints.

    To configure the endpoint details of a containerized component, Choreo looks for an endpoints.yaml file inside the .choreo directory. Be sure to place the .choreo directory at the root of the Docker build context path.

    In the greeter sample, the endpoints.yaml file is in the greeting-service-go/.choreo/ directory.

    "},{"location":"develop-components/develop-services/develop-a-service-with-docker/#step-1-create-a-service-component-from-a-dockerfile","title":"Step 1: Create a service component from a Dockerfile","text":"

    To create a containerized service component, follow these steps:

    1. Go to https://console.choreo.dev/ and sign in. This opens the project home page.
    2. If you already have one or more components in your project, click + Create. Otherwise, proceed to the next step.
    3. Click the Service card.

    4. Enter a display name, a unique name, and a description for the service component. You can enter the values given below:

      Info

      In the Component Name field, you must specify a name to uniquely identify the component in various contexts. The value is editable only at the time you create the component. You cannot change the name after you create the component.

      Field Value Component Display Name Greetings Component Name greetings Description Send greetings

    5. Go to the GitHub tab.

    6. To allow Choreo to connect to your GitHub account, click Authorize with GitHub. If you have not already connected your GitHub repository to Choreo, enter your GitHub credentials and select the repository you created in the prerequisites section to install the Choreo GitHub App.

      Alternatively, you can paste the Choreo samples repository URL in the Provide Repository URL field to connect to it without requiring authorization from the Choreo Apps GitHub application. However, authorizing the repository with the Choreo GitHub App is necessary if you want to enable Auto Deploy for the component.

      Note

      The Choreo GitHub App requires the following permissions:

      • Read and write access to code and pull requests.
      • Read access to issues and metadata.

      You can revoke access if you do not want Choreo to have access to your GitHub account. However, write access is exclusively utilized for sending pull requests to a user repository. Choreo will not directly push any changes to a repository.

    7. Under Connect Your Repository, enter the following information:

      Field Value Organization Your GitHub account Repository choreo-samples Branch main

    8. Select Docker as the buildpack.

    9. Enter the following information:

      Field Value Docker Context /greeting-service-go Dockerfile /greeting-service-go/Dockerfile

      Info

      1. To successfully build your container with Choreo, it is essential to explicitly define a user ID (UID) under the USER instruction in your Dockerfile. For reference, see sample Dockerfile. To ensure that the defined USER instruction is valid, it must conform to the following conditions:

        • A valid User ID is a numeric value between 10000-20000, such as 10001 or 10500.
        • Usernames are considered invalid and should not be used. For example, my-custom-user-12221 or my-custom-user are invalid User IDs.

      2. The Dockerfile used in this guide is a multi-stage Dockerfile, which is designed to keep the final image size small and provides the ability to build the application with a specific version of tools and libraries.

    10. Click Create. This creates the component and takes you to the Overview page of the component.

    You have successfully created a service from a Dockerfile. Next, you can build and deploy the service.

    "},{"location":"develop-components/develop-services/develop-a-service-with-docker/#step-2-build-and-deploy","title":"Step 2: Build and deploy","text":"

    Now that we have connected the source repository, and configured the endpoint details, it's time to build the service and create an image. Then we can deploy that image test the greeter service.

    "},{"location":"develop-components/develop-services/develop-a-service-with-docker/#step-21-build","title":"Step 2.1: Build","text":"

    To build the service, follow these steps:

    1. In the left navigation menu, click Build.

    2. On the Build page, click Build Latest.

      Note

      Building the service component may take a while. You can track the progress via the logs in the Build Details pane. Once the build process is complete, the build status changes to Success.

      You can access the following scans under Build.

      • The Dockerfile scan: Choreo performs a scan to check if a non-root user ID is assigned to the Docker container to ensure security. If no non-root user is specified, the build will fail.
      • Container (Trivy) vulnerability scan: This detects vulnerabilities in the final docker image.

      • Container (Trivy) vulnerability scan: The details of the vulnerabilities open in a separate pane. If this scan detects critical vulnerabilities, the build will fail.

        Info

        If you have Choreo environments on a private data plane, you can ignore these vulnerabilities and proceed with the deployment.

    "},{"location":"develop-components/develop-services/develop-a-service-with-docker/#step-22-deploy","title":"Step 2.2: Deploy","text":"

    To deploy the service, follow these steps:

    1. In the left navigation menu, click Deploy.
    2. On the Set Up card, click Configure & Deploy.
    3. In the Environment Configurations pane that opens, click Next to skip the configuration.
    4. In the File Mount pane, click Next to skip the configuration.

    5. Review the Endpoint Details and click Deploy.

      Note

      Deploying the service component may take a while. Once deployed, the Development environment card indicates the Deployment Status as Active.

    Once you have successfully deployed the service, you can test, manage, and observe it like any other component type in Choreo.

    To perform a more detailed diagnosis of this Dockerfile-based REST API by viewing Kubernetes-level insights, see Choreo's DevOps capabilities.

    "},{"location":"develop-components/develop-services/develop-a-service/","title":"Develop a Service","text":"

    Choreo allows you to create and deploy applications in your preferred programming language.

    In this guide, you will:

    • Build a simple greeting service using a sample service implementation. The sample implementation will have a single resource named greet that accepts a single query parameter as input.
    • Deploy the service in Choreo using a Go buildpack. The service will run on port 9090.
    • Test the service.
    "},{"location":"develop-components/develop-services/develop-a-service/#prerequisites","title":"Prerequisites","text":"

    Before you try out this guide, complete the following:

    • If you are signing in to the Choreo Console for the first time, create an organization as follows:

      1. Go to https://console.choreo.dev/, and sign in using your preferred method.
      2. Enter a unique organization name. For example, Stark Industries.
      3. Read and accept the privacy policy and terms of use.
      4. Click Create.

      This creates the organization and opens the Project Home page of the default project created for you.

    • Fork the Choreo samples repository, which contains the sample greetings service implementation in Go.

    "},{"location":"develop-components/develop-services/develop-a-service/#learn-the-repository-file-structure","title":"Learn the repository file structure","text":"

    It is important to understand the purpose of the key files in the sample service. The following table provides a brief overview of each file in the greeter service:

    Note

    The specified file paths are relative to <sample-repository-dir>/greeting-service-go

    Filepath Description main.go The Go-based greeter service code. .choreo/endpoints.yaml Choreo-specific configuration that provides information about how Choreo exposes the service. openapi.yaml The OpenAPI contract of the greeter service. This is required to publish the service as a managed API. This openapi.yaml file is referenced by the .choreo/endpoints.yaml file.

    Let's get started!

    "},{"location":"develop-components/develop-services/develop-a-service/#configure-the-service-port-with-endpoints","title":"Configure the service port with endpoints","text":"

    In Choreo, you can expose your services via endpoints.

    You are going to run the greeter service on port 9090. To securely expose the service through Choreo, you must provide the port and other required information to Choreo. For detailed information on each attribute of an endpoint, see Configure Endpoints.

    To configure the endpoint details of a containerized component, Choreo looks for an endpoints.yaml file inside the .choreo directory. Be sure to place the .choreo directory at the root of the Docker build context path.

    In the greeter sample, the endpoints.yaml file is in the greeting-service-go/.choreo/ directory.

    "},{"location":"develop-components/develop-services/develop-a-service/#step-1-create-a-service-component","title":"Step 1: Create a service component","text":"

    To create a containerized service component, follow these steps:

    1. Go to https://console.choreo.dev/ and sign in. This opens the project home page.
    2. If you already have one or more components in your project, click + Create. Otherwise, proceed to the next step.
    3. Click the Service card.

    4. Enter a display name, a unique name, and a description for the service component. You can enter the values given below:

      Info

      In the Component Name field, you must specify a name to uniquely identify the component in various contexts. The value is editable only at the time you create the component. You cannot change the name after you create the component.

      Field Value Component Display Name Greetings Component Name greetings Description Send greetings

    5. Go to the GitHub tab.

    6. To allow Choreo to connect to your GitHub account, click Authorize with GitHub. If you have not already connected your GitHub repository to Choreo, enter your GitHub credentials and select the repository you created in the prerequisites section to install the Choreo GitHub App.

      Alternatively, you can paste the Choreo samples repository URL in the Provide Repository URL field to connect to it without requiring authorization from the Choreo Apps GitHub application. However, authorizing the repository with the Choreo GitHub App is necessary if you want to enable Auto Deploy for the component.

      Note

      The Choreo GitHub App requires the following permissions:

      • Read and write access to code and pull requests.
      • Read access to issues and metadata.

      You can revoke access if you do not want Choreo to have access to your GitHub account. However, write access is exclusively utilized for sending pull requests to a user repository. Choreo will not directly push any changes to a repository.

    7. Under Connect Your Repository, enter the following information:

      Field Value Organization Your GitHub account GitHub Repository choreo-samples Branch main

    8. Select Go as the buildpack.

    9. Enter the following information:

      Field Value Go Project Directory /greeting-service-go Language Version 1.x

    10. Click Create. This creates the component and lists it under Component Listing on the project home page.

    You have successfully created the service. The next step is to build and deploy it.

    "},{"location":"develop-components/develop-services/develop-a-service/#step-2-build-and-deploy","title":"Step 2: Build and deploy","text":"

    Now that you have connected the source repository and configured the endpoint details, it's time to build and deploy the greeter service.

    "},{"location":"develop-components/develop-services/develop-a-service/#step-21-build","title":"Step 2.1: Build","text":"

    To build the service, follow these steps:

    1. On the project home page, click on the Greetings component you created. This takes you to the component overview page.
    2. In the left navigation menu, click Build.

    3. On the Build page, click Build Latest.

      Note

      Building the service component may take a while. You can track the progress via the logs in the Build Details pane. Once the build process is complete, the build status changes to Success.

    "},{"location":"develop-components/develop-services/develop-a-service/#step-22-deploy","title":"Step 2.2: Deploy","text":"

    To deploy the service, follow these steps:

    1. In the left navigation menu, click Deploy.
    2. On the Set Up card, click Configure & Deploy.
    3. In the Environment Configurations pane that opens, click Next to skip the configuration.
    4. In the File Mount pane, click Next to skip the configuration.

    5. Review the Endpoint Details and click Deploy.

      Note

      Deploying the service component may take a while. Once deployed, the Development environment card indicates the Deployment Status as Active.

    Once you have successfully deployed the service, you can test, manage, and observe it like any other component type in Choreo.

    "},{"location":"develop-components/develop-services/expose-a-ballerina-graphql-endpoint-via-a-service/","title":"Expose a Ballerina GraphQL Endpoint via a Service","text":"

    Choreo offers the flexibility to develop and deploy applications in a language of your preference. This guide shows you how to deploy a service component that exposes a GraphQL API using the Ballerina language in Choreo. No prior knowledge of the Ballerina language is required to follow this guide.

    GraphQL API is a query language and runtime that provides a single endpoint for retrieving flexible and efficient data in a strongly-typed and self-documenting way. By following this guide, you will build a service component in Ballerina and deploy it on Choreo for any GraphQL client application to utilize it.

    This guide shows how to build a simple reading list service and deploy it in Choreo using Ballerina. The GraphQL endpoint you create in this guide has two operations: Query and Mutation. The Query type operations read the data in the data source, and the Mutation operations update the data in the data source. The reading list service has two queries and three mutations as follows:

    "},{"location":"develop-components/develop-services/expose-a-ballerina-graphql-endpoint-via-a-service/#queries","title":"Queries","text":"

    Retrieve the reading list

    This resource accepts an optional filter, status, which filters the reading list by reading status. Accepted values for status are reading, read, and to_read.

    Sample request: 

    $ curl -X POST -H \"Content-Type: application/json\" -d '{\"query\": \"query {allBooks (status: \\\"reading\\\") { id title author status }}\"}' http://localhost:8090\n

    Sample response 

    $ {\n  \"data\": {\n    \"allBooks\": [\n      {\n        \"id\": 1,\n        \"title\": \"Sample Book\",\n        \"author\": \"Test Author\",\n        \"status\": \"to_read\"\n      }\n    ]\n  }\n}\n

    Retrieve a book item from the reading list

    This resource accepts a filter, id, which will select the book item from the reading list by book id. The id is an Integer value.

    Sample request 

    $ curl -X POST -H \"Content-Type: application/json\" -d '{\"query\": \"query {book (id: 1) { id title author status }}\"}' http://localhost:8090\n

    Sample response 

    $ {\n  \"data\": {\n    \"book\": {\n      \"id\": 1,\n      \"title\": \"Sample Book\",\n      \"author\": \"Test Author\",\n      \"status\": \"to_read\"\n    }\n  }\n}\n

    "},{"location":"develop-components/develop-services/expose-a-ballerina-graphql-endpoint-via-a-service/#mutations","title":"Mutations","text":"

    Add a book item to the reading list

    This remote function accepts a book record as the input and consists of the title and the author. When you add a new book to the reading list, the method updates the reading status of the newly added book to to_read. This method returns the added book item upon successful execution.

    Sample request

    $ curl -X POST -H \"Content-type: application/json\" -d '{ \"query\": \"mutation { addBook(book: {title: \\\"Sample Book\\\", author: \\\"Test Author\\\"}) { id title author status } }\" }' 'http://localhost:8090'\n

    Sample response

    $ {\n  \"data\": {\n    \"addBook\": {\n      \"id\": 1,\n      \"title\": \"Sample Book\",\n      \"author\": \"Test Author\",\n      \"status\": \"to_read\"\n    }\n  }\n}\n

    Update the reading status of a book

    This remote function requires id and status as inputs to update the reading status of the selected book. The id refers to the id of the book. It is an integer. The status refers to the reading status that needs to be updated. This method returns the updated book item upon successful execution.

    Sample request

    $ curl -X POST -H \"Content-type: application/json\" -d '{ \"query\": \"mutation { setStatus(id: 1, status: \\\"reading\\\") { id title author status } }\" }' 'http://localhost:8090'\n

    Sample response

    $ {\n  \"data\": {\n    \"setStatus\": {\n      \"id\": 1,\n      \"title\": \"Sample Book\",\n      \"author\": \"Test Author\",\n      \"status\": \"reading\"\n    }\n  }\n}\n

    Delete a book item from the reading list

    This remote function requires the id as the input to delete the book item from the reading list. This method returns the removed book item upon successful execution.

    Sample request

    $ curl -X POST -H \"Content-type: application/json\" -d '{ \"query\": \"mutation { deleteBook(id: 1) { id title author status } }\" }' 'http://localhost:8090'\n

    Sample response 

    $ {\n  \"data\": {\n    \"deleteBook\": {\n      \"id\": 1,\n      \"title\": \"Sample Book\",\n      \"author\": \"Test Author\",\n      \"status\": \"reading\"\n    }\n  }\n}\n

    Our next step is to set up the resources that you will require to follow the guide, including the sample reading list application and the Choreo GitHub app.

    "},{"location":"develop-components/develop-services/expose-a-ballerina-graphql-endpoint-via-a-service/#prerequisites","title":"Prerequisites","text":"

    • If you are signing in to the Choreo Console for the first time, create an organization as follows:

      1. Go to https://console.choreo.dev/, and sign in using your preferred method.
      2. Enter a unique organization name. For example, Stark Industries.
      3. Read and accept the privacy policy and terms of use.
      4. Click Create.

      This creates the organization and opens the Project Home page of the default project created for you.

    • Fork the Choreo samples repository, which contains the sample GraphQL service implementation for this guide.

    Let's get started!

    "},{"location":"develop-components/develop-services/expose-a-ballerina-graphql-endpoint-via-a-service/#learn-the-repository-file-structure","title":"Learn the repository file structure","text":"

    It is important to understand the purpose of the key files in the sample service. The following table provides a brief overview of each file in the reading list service.

    Note

    The following file paths are relative to the path <sample-repository-dir>/reading-list-graphql.

    Filepath Description service.bal The reading list service code written in the Ballerina language. Ballerina.toml The Ballerina configuration file. .choreo/endpoints.yaml The configuration file with endpoint details."},{"location":"develop-components/develop-services/expose-a-ballerina-graphql-endpoint-via-a-service/#step-1-create-a-service-component","title":"Step 1: Create a service component","text":"

    To create a Ballerina service component, follow these steps:

    1. Go to https://console.choreo.dev/ and sign in. This opens the project home page.
    2. If you already have one or more components in your project, click + Create. Otherwise, proceed to the next step.
    3. Click the Service card.

    4. Enter a display name, a unique name, and a description for the service component. You can enter the values given below:

      Info

      In the Component Name field, you must specify a name to uniquely identify the component in various contexts. The value is editable only at the time you create the component. You cannot change the name after you create the component.

      Field Value Component Display Name Ballerina Reading List Component Name ballerina-reading-list Description Manage a reading list

    5. Click the GitHub tab.

    6. To allow Choreo to connect to your GitHub account, click Authorize with GitHub. If you have not already connected your GitHub repository to Choreo, enter your GitHub credentials and select the repository you created in the prerequisites section to install the Choreo GitHub App.

      Alternatively, you can paste the Choreo samples repository URL in the Provide Repository URL field to connect to it without requiring authorization from the Choreo Apps GitHub application. However, authorizing the repository with the Choreo GitHub App is necessary if you want to enable Auto Deploy for the component.

      Note

      The Choreo GitHub App requires the following permissions:

      • Read and write access to code and pull requests.
      • Read access to issues and metadata.

      You can revoke access if you do not want Choreo to have access to your GitHub account. However, write access is exclusively utilized for sending pull requests to a user repository. Choreo will not directly push any changes to a repository.

    7. Under Connect Your Repository, enter the following information:

      Field Value Organization Your GitHub account GitHub Repository choreo-samples Branch main

    8. Select Ballerina as the buildpack.

    9. Enter the following information:

      Field Value Ballerina Project Directory reading-list-graphql

    10. Click Create. This creates the component and takes you to the Overview page of the component.

    You have successfully created a service component that exposes a GraphQL API written in the Ballerina language. Next, let's build and deploy the service.

    "},{"location":"develop-components/develop-services/expose-a-ballerina-graphql-endpoint-via-a-service/#step-2-build-and-deploy","title":"Step 2: Build and deploy","text":"

    Now that we have connected the source repository, it's time to build and deploy the reading list service.

    "},{"location":"develop-components/develop-services/expose-a-ballerina-graphql-endpoint-via-a-service/#step-21-build","title":"Step 2.1: Build","text":"

    To build the service, follow these steps:

    1. In the left navigation menu, click Build.

    2. On the Build page, click Build Latest.

      Note

      Building the service component may take a while. You can track the progress via the logs in the Build Details pane. Once the build process is complete, the build status changes to Success.

    "},{"location":"develop-components/develop-services/expose-a-ballerina-graphql-endpoint-via-a-service/#step-22-deploy","title":"Step 2.2: Deploy","text":"

    To deploy the service, follow these steps:

    1. In the left navigation menu, click Deploy.
    2. On the Set Up card, click Configure & Deploy.
    3. In the Configurations pane that opens, click Next to skip the configuration.

    4. Review the Endpoint Details and click Deploy.

      Note

      Deploying the service component may take a while. Once deployed, the Development environment card indicates the Deployment Status as Active.

      To build and deploy the service, follow the steps below:

    Once you have successfully deployed your service, you can test, manage, and observe it like any other component type in Choreo.

    For detailed instructions, see the following sections:

    • Step 3: Test
    • Step 4: Manage
    "},{"location":"develop-components/develop-services/expose-a-grpc-endpoint-via-a-service/","title":"Expose a gRPC Endpoint via a Service","text":"

    Choreo allows you to create and deploy applications in your preferred programming language. One powerful option is gRPC, a high-performance and language-agnostic remote procedure call (RPC) framework. It utilizes Protocol Buffers to define services and generate client/server code.

    In this guide, you will learn to use Choreo to create a service component that exposes a gRPC server implemented in Go, enabling efficient and scalable communication with any gRPC client application. No prior knowledge of the Go language is necessary to follow this guide.

    By following this guide, you will:

    • Create a simple gRPC server using a Service component.

    • Link the containerized gRPC service to the Choreo component using the Dockerfile. The greeter service has a single RPC method named sayHello. Following is the proto file the server and the client application are using:

      syntax = \"proto3\";\noption go_package = \"github.com/wso2/choreo-samples/go-grpc/pkg\";\nservice greeter {\nrpc SayHello (HelloRequest) returns (HelloReply) {}\n}\nmessage HelloRequest {\nstring name = 1;\n}\nmessage HelloReply {\nstring message = 1;\n}\n

    • Deploy the gRPC server component in Choreo.

    • Create a gRPC client using a Manual Trigger component.
    • Deploy the gRPC client.
    • Invoke the gRPC server using a gRPC client and check the response through the Choreo log view.
    "},{"location":"develop-components/develop-services/expose-a-grpc-endpoint-via-a-service/#prerequisites","title":"Prerequisites","text":"

    Before you try out this guide, complete the following:

    • If you are signing in to the Choreo Console for the first time, create an organization as follows:

      1. Go to https://console.choreo.dev/, and sign in using your preferred method.
      2. Enter a unique organization name. For example, Stark Industries.
      3. Read and accept the privacy policy and terms of use.
      4. Click Create.

      This creates the organization and opens the Project Home page of the default project created for you.

    • Fork the Choreo samples repository, which contains the sample service implementation for this guide.

    Let's get started!

    "},{"location":"develop-components/develop-services/expose-a-grpc-endpoint-via-a-service/#learn-the-repository-file-structure","title":"Learn the repository file structure","text":"

    It is important to understand the purpose of the key files in the sample service. The following table provides a brief overview of each file in the greeter service.

    Note

    The following file paths are relative to the path <sample-repository-dir>/go-grpc.

    File Path Description main.go The greeter service code written in the Go language. greeter_client/main.go The greeter client application written in the Go language. Dockerfile.server The Dockerfile to build the container image of the server application. Dockerfile.client The Dockerfile to build the container image of the client application. .choreo/endpoints.yaml The Choreo-specific configuration that provides information about how Choreo exposes the service. pkg/greeter.proto The interface definition of the gRPC service. This is used to generate the server and client stubs for the Go application."},{"location":"develop-components/develop-services/expose-a-grpc-endpoint-via-a-service/#configure-the-service-port-with-endpoints","title":"Configure the service port with endpoints","text":"

    In Choreo, you can expose your services via endpoints.

    Let's run the gRPC server service component on port 8080. To securely expose the service through Choreo, you must provide the port and other required information to Choreo. For detailed information on each attribute of an endpoint, see Configure Endpoints.

    Choreo looks for an endpoints.yaml file inside the .choreo directory to configure the endpoint details of the containerized component. Ensure the .choreo directory is at the root of the Docker build context path.

    In the gRPC server sample, the endpoints.yaml file is at go-grpc/.choreo/endpoints.yaml, where the build context path is go-grpc.

    "},{"location":"develop-components/develop-services/expose-a-grpc-endpoint-via-a-service/#step-1-create-a-service-component-with-a-grpc-endpoint","title":"Step 1: Create a service component with a gRPC endpoint","text":"

    To create a containerized service component, follow these steps:

    1. Go to https://console.choreo.dev/ and sign in. This opens the project home page.
    2. If you already have one or more components in your project, click + Create. Otherwise, proceed to the next step.
    3. Click the Service card.

    4. Enter a display name, a unique name, and a description for the service component. You can enter the values given below:

      Info

      In the Component Name field, you must specify a name to uniquely identify the component in various contexts. The value is editable only at the time you create the component. You cannot change the name after you create the component.

      Field Value Component Display Name Go gRPC Server Component Name go-grpc-server Description Send greetings

    5. Click the GitHub tab.

    6. To allow Choreo to connect to your GitHub account, click Authorize with GitHub. If you have not already connected your GitHub repository to Choreo, enter your GitHub credentials and select the repository you created in the prerequisites section to install the Choreo GitHub App.

      Alternatively, you can paste the Choreo samples repository URL in the Provide Repository URL field to connect to it without requiring authorization from the Choreo Apps GitHub application. However, authorizing the repository with the Choreo GitHub App is necessary if you want to enable Auto Deploy for the component.

      Note

      The Choreo GitHub App requires the following permissions:

      • Read and write access to code and pull requests.
      • Read access to issues and metadata.

      You can revoke access if you do not want Choreo to have access to your GitHub account. However, write access is exclusively utilized for sending pull requests to a user repository. Choreo will not directly push any changes to a repository.

    7. Under Connect Your Repository, enter the following information:

      Field Value Organization Your GitHub account GitHub Repository choreo-samples Branch main

    8. Select Docker as the buildpack.

    9. Enter the following information:

      Field Value Docker Context go-grpc Dockerfile go-grpc/Dockerfile.server

      Info

      1. To successfully build your container with Choreo, it is essential to explicitly define a User ID (UID) under the USER instruction in your Dockerfile. For reference, see the sample Dockerfile. To ensure that the defined USER instruction is valid, it must conform to the following conditions:

        • A valid User ID is a numeric value between 10000-20000, such as 10001 or 10500.
        • Usernames are considered invalid and should not be used. For example, my-custom-user-12221 or my-custom-user are invalid User IDs.

      2. The Dockerfile utilized in this guide is a multi-stage Dockerfile, which is designed to keep the final image size small and provides the ability to build the application with a specific version of tools and libraries.

    10. Click Create. This creates the component and takes you to the Overview page of the component.

    You have successfully created a service from a Dockerfile. Next, you can build and deploy the service.

    "},{"location":"develop-components/develop-services/expose-a-grpc-endpoint-via-a-service/#step-2-build-and-deploy","title":"Step 2: Build and deploy","text":"

    Now that you have connected the source repository, and configured the endpoint details, it's time to build the service and create an image. Then you can deploy the image and test the greeter service.

    "},{"location":"develop-components/develop-services/expose-a-grpc-endpoint-via-a-service/#step-21-build","title":"Step 2.1: Build","text":"

    To build the service, follow these steps:

    1. In the left navigation menu, click Build.

    2. On the Build page, click Build Latest.

      Note

      Building the service component may take a while. You can track the progress via the logs in the Build Details pane. Once the build process is complete, the build status changes to Success.

      You can access the following scans under Build.

      • The Dockerfile scan: Choreo performs a scan to check if a non-root user ID is assigned to the Docker container to ensure security. If no non-root user is specified, the build will fail.
      • Container (Trivy) vulnerability scan: This detects vulnerabilities in the final docker image.

      • Container (Trivy) vulnerability scan: The details of the vulnerabilities open in a separate pane. If this scan detects critical vulnerabilities, the build will fail.

        Info

        If you have Choreo environments on a private data plane, you can ignore these vulnerabilities and proceed with the deployment.

    "},{"location":"develop-components/develop-services/expose-a-grpc-endpoint-via-a-service/#step-22-deploy","title":"Step 2.2: Deploy","text":"

    To deploy the service, follow these steps:

    1. In the left navigation menu, click Deploy.
    2. On the Set Up card, click Configure & Deploy.
    3. In the Environment Configurations pane that opens, click Next to skip the configuration.
    4. In the File Mount pane, click Next to skip the configuration.

    5. Review the Endpoint Details and click Deploy.

      Note

      Deploying the service component may take a while. Once deployed, the Development environment card indicates the Deployment Status as Active.

    6. Once you have successfully deployed your service, navigate to the component overview page and copy the gRPC service URL. You need to provide that URL when setting up the client application later in this guide.

    You have successfully deployed the gRPC server. Currently, the gRPC service is only accessible by the components deployed within the same project.

    "},{"location":"develop-components/develop-services/expose-a-grpc-endpoint-via-a-service/#step-3-invoke-the-grpc-service","title":"Step 3: Invoke the gRPC service","text":"

    Let's invoke the gRPC service that you created above, using a gRPC client.

    "},{"location":"develop-components/develop-services/expose-a-grpc-endpoint-via-a-service/#step-31-create-a-manual-task-for-the-grpc-client","title":"Step 3.1: Create a manual task for the gRPC client","text":"

    To create a manual task component, follow these steps:

    1. On the Choreo Console header, click the Project list and select the project where you created the gRPC service component. This opens the project home page.
    2. Go to the Component Listing section and click + Create.
    3. Click the Manual Task card.

    4. Enter a display name, a unique name, and a description for the component. You can enter the values given below:

      Info

      In the Component Name field, you must specify a name to uniquely identify the component in various contexts. The value is editable only at the time you create the component. You cannot change the name after you create the component.

      Field Value Component Display Name Go gRPC Client Component Name go-grpc-client Description Receive greetings

    5. Click the GitHub tab.

    6. To allow Choreo to connect to your GitHub account, click Authorize with GitHub. If you have not already connected your GitHub repository to Choreo, enter your GitHub credentials and select the repository you created in the prerequisites section to install the Choreo GitHub App.

      Alternatively, you can paste the Choreo samples repository URL in the Provide Repository URL field to connect to it without requiring authorization from the Choreo Apps GitHub application. However, authorizing the repository with the Choreo GitHub App is necessary if you want to enable Auto Deploy for the component.

      Note

      The Choreo GitHub App requires the following permissions:

      • Read and write access to code and pull requests.
      • Read access to issues and metadata.

      You can revoke access if you do not want Choreo to have access to your GitHub account. However, write access is exclusively utilized for sending pull requests to a user repository. Choreo will not directly push any changes to a repository.

    7. Under Connect Your Repository, enter the following information:

      Field Value Organization Your GitHub account GitHub Repository choreo-samples Branch main

    8. Select Docker as the buildpack.

    9. Enter the following information:

      Field Value Docker Context go/grpc Dockerfile go/grpc/Dockerfile.client

    10. Click Create. This creates the component and takes you to the Overview page of the component.

    "},{"location":"develop-components/develop-services/expose-a-grpc-endpoint-via-a-service/#step-32-build-the-grpc-client-component","title":"Step 3.2: Build the gRPC client component","text":"

    To build the component, follow these steps:

    1. In the left navigation menu, click Build.

    2. On the Build page, click Build Latest.

      Note

      Building the service component may take a while. You can track the progress via the logs in the Build Details pane. Once the build process is complete, the build status changes to Success.

    "},{"location":"develop-components/develop-services/expose-a-grpc-endpoint-via-a-service/#step-33-setup-environment-variables-and-deploy-the-grpc-client","title":"Step 3.3: Setup environment variables and deploy the gRPC client","text":"

    The client application, in this case, the gRPC client, requires the server URL of the gRPC server service. This is read from the client application as an environment variable. Follow the steps below to configure the environment variable for the client application:

    1. On the Choreo Console left navigation menu, click Deploy.
    2. In the Set Up card, click Configure & Deploy.
    3. In the Environment Configurations pane that opens, click + Add.

    4. Specify the following name and value to configure the environment variable for the client application:

      Field Value Name GREETER_SERVICE Value Paste the URL value copied after deploying the gRPC service via step 2.2 above. Make sure to drop the http:// or grpc:// part and the trailing / from the URL when copying. For example, if the URL is http://go-grpc-server-3192360657:8080/, add only go-grpc-server-3192360657:8080.

    5. Click Add and then click Next.

    6. Click Deploy.
    "},{"location":"develop-components/develop-services/expose-a-grpc-endpoint-via-a-service/#step-34-execute-the-grpc-client-component","title":"Step 3.4: Execute the gRPC client component","text":"

    To execute the gRPC client, follow these steps:

    1. In the left navigation menu, click Execute.
    2. Click Run Now. This triggers the gRPC client and generates logs. You can trigger multiple runs to generate multiple logs.

    For details on what you can monitor via the execute page, see Monitor executions.

    "},{"location":"develop-components/develop-services/expose-a-tcp-server-via-a-service/","title":"Expose a TCP Server via a Service","text":"

    Choreo offers the flexibility to design and deploy applications in the programming language of your choice. One viable choice for specific network communication needs is TCP (Transmission Control Protocol). TCP provides a reliable, stream-oriented communication mechanism that ensures data integrity and orderliness during transmission. It's the go-to option for scenarios where guaranteed data delivery and error recovery are paramount.

    In this guide, you will learn to use Choreo to create a service component that exposes a TCP server implemented in Go, enabling efficient and scalable communication with any TCP client application. No prior knowledge of the Go language is necessary to follow this guide.

    By following this guide, you will:

    • Setup a TCP server
      • Create a simple TCP server using a service component.
      • Link the containerized TCP service to the Choreo component using a Dockerfile.
      • Deploy the TCP server component in Choreo.
    • Setup a TCP client
      • Create a TCP client using a manual task component.
      • Link the containerized TCP client to the Choreo component using a Dockerfile.
      • Deploy the TCP client component in Choreo.
    • Invoke the TCP server using a TCP client and observe the response through the Choreo log view.
    "},{"location":"develop-components/develop-services/expose-a-tcp-server-via-a-service/#prerequisites","title":"Prerequisites","text":"

    Before you try out this guide, complete the following:

    • If you are signing in to the Choreo Console for the first time, create an organization as follows:

      1. Go to https://console.choreo.dev/, and sign in using your preferred method.
      2. Enter a unique organization name. For example, Stark Industries.
      3. Read and accept the privacy policy and terms of use.
      4. Click Create.

      This creates the organization and opens the Project Home page of the default project created for you.

    • Fork the Choreo samples repository, which contains the sample service implementation for this guide.

    Let's get started!

    "},{"location":"develop-components/develop-services/expose-a-tcp-server-via-a-service/#learn-the-repository-file-structure","title":"Learn the repository file structure","text":"

    It is important to understand the purpose of the key files in the sample service. The following table provides a brief overview of each file in the sample service.

    Note

    The following file paths are relative to the path <sample-repository-dir>/docker-tcp-service.

    File Path Description server/main.go The greeter service code written in the Go language. client/main.go The greeter client application written in the Go language. Dockerfile.server The Dockerfile to build the container image of the server application. Dockerfile.client The Dockerfile to build the container image of the client application. .choreo/endpoints.yaml The Choreo-specific configuration provides information about how Choreo exposes the service."},{"location":"develop-components/develop-services/expose-a-tcp-server-via-a-service/#configure-the-service-port-with-endpoints","title":"Configure the service port with endpoints","text":"

    In Choreo, you can expose your services via endpoints.

    Let's run the TCP server service component on port 5050. To securely expose the service through Choreo, you must provide the port and other required information to Choreo. For detailed information on each attribute of an endpoint, see Configure Endpoints.

    Choreo looks for an endpoints.yaml file inside the .choreo directory to configure the endpoint details of a containerized component. Place the .choreo directory at the root of the Docker build context path.

    In our TCP server sample, the endpoints.yaml file is at docker-tcp-service/.choreo/endpoints.yaml, where the build context path is docker-tcp-service.

    "},{"location":"develop-components/develop-services/expose-a-tcp-server-via-a-service/#step-1-create-a-service-component-with-a-tcp-endpoint","title":"Step 1: Create a service component with a TCP endpoint","text":"

    To create a containerized service component, follow these steps:

    1. Go to https://console.choreo.dev/ and sign in. This opens the project home page.
    2. If you already have one or more components in your project, click + Create. Otherwise, proceed to the next step.
    3. Click the Service card.

    4. Enter a display name, a unique name, and a description for the service component. You can enter the values given below:

      Info

      In the Component Name field, you must specify a name to uniquely identify the component in various contexts. The value is editable only at the time you create the component. You cannot change the name after you create the component.

      Field Value Component Display Name Go TCP Server Component Name go-tcp-server Description Send greetings

    5. Click the GitHub tab.

    6. To allow Choreo to connect to your GitHub account, click Authorize with GitHub. If you have not already connected your GitHub repository to Choreo, enter your GitHub credentials and select the repository you created in the prerequisites section to install the Choreo GitHub App.

      Alternatively, you can paste the Choreo samples repository URL in the Provide Repository URL field to connect to it without requiring authorization from the Choreo Apps GitHub application. However, authorizing the repository with the Choreo GitHub App is necessary if you want to enable Auto Deploy for the component.

      Note

      The Choreo GitHub App requires the following permissions:

      • Read and write access to code and pull requests.
      • Read access to issues and metadata.

      You can revoke access if you do not want Choreo to have access to your GitHub account. However, write access is exclusively utilized for sending pull requests to a user repository. Choreo will not directly push any changes to a repository.

    7. Under Connect Your Repository, enter the following information:

      Field Value Organization Your GitHub account GitHub Repository choreo-samples Branch main

    8. Select Docker as the buildpack.

    9. Enter the following information:

      Field Value Docker Context docker-tcp-service Dockerfile docker-tcp-service/Dockerfile.server

      Info

      1. To successfully build your container with Choreo, it is essential to explicitly define a User ID (UID) under the USER instruction in your Dockerfile. For reference, see the sample Dockerfile. To ensure that the defined USER instruction is valid, it must conform to the following conditions:

        • A valid User ID is a numeric value between 10000-20000, such as 10001 or 10500.
        • Usernames are considered invalid and should not be used. For example, my-custom-user-12221 or my-custom-user are invalid User IDs.

      2. The Dockerfile utilized in this guide is a multi-stage Dockerfile, which is designed to keep the final image size small and provides the ability to build the application with a specific version of tools and libraries.

    10. Click Create. This creates the component and takes you to the Overview page of the component.

    You have successfully created a service from a Dockerfile. Next, you can build and deploy the service.

    "},{"location":"develop-components/develop-services/expose-a-tcp-server-via-a-service/#step-2-build-and-deploy","title":"Step 2: Build and deploy","text":"

    Now that you have connected the source repository, and configured the endpoint details, it's time to build the service and create an image. Then you can deploy the image and test the service.

    "},{"location":"develop-components/develop-services/expose-a-tcp-server-via-a-service/#step-21-build","title":"Step 2.1: Build","text":"

    To build the service, follow these steps:

    1. In the left navigation menu, click Build.

    2. On the Build page, click Build Latest.

      Note

      Building the service component may take a while. You can track the progress via the logs in the Build Details pane. Once the build process is complete, the build status changes to Success.

      You can access the following scans under Build.

      • The Dockerfile scan: Choreo performs a scan to check if a non-root user ID is assigned to the Docker container to ensure security. If no non-root user is specified, the build will fail.
      • Container (Trivy) vulnerability scan: This detects vulnerabilities in the final docker image.

      • Container (Trivy) vulnerability scan: The details of the vulnerabilities open in a separate pane. If this scan detects critical vulnerabilities, the build will fail.

        Info

        If you have Choreo environments on a private data plane, you can ignore these vulnerabilities and proceed with the deployment.

    "},{"location":"develop-components/develop-services/expose-a-tcp-server-via-a-service/#step-22-deploy","title":"Step 2.2: Deploy","text":"

    To deploy the service, follow these steps:

    1. In the left navigation menu, click Deploy.
    2. On the Set Up card, click Configure & Deploy.
    3. In the Environment Configurations pane that opens, click Next to skip the configuration.
    4. In the File Mount pane, click Next to skip the configuration.

    5. Review the Endpoint Details and click Deploy.

      Note

      Deploying the service component may take a while. Once deployed, the Development environment card indicates the Deployment Status as Active.

    6. Once you have successfully deployed your service, navigate to the component overview page and copy the TCP service address. You need to provide that address when setting up the client application later in this guide.

    You have successfully deployed the TCP server. Currently, the TCP service is only accessible by the components deployed within the same project.

    "},{"location":"develop-components/develop-services/expose-a-tcp-server-via-a-service/#step-3-invoke-the-tcp-service","title":"Step 3: Invoke the TCP service","text":"

    Now let's use a TCP client to invoke the TCP service that you created above. To do this, you can create a manual trigger component as the TCP client. This is the recommended approach because, in this example, it's more efficient to have a client that connects to the server, sends a request, and then stops. Here, a continuously executing task isn't required. Furthermore, if you use a manual trigger component, you won't need to expose an endpoint in the client for invocation, unlike with an API.

    "},{"location":"develop-components/develop-services/expose-a-tcp-server-via-a-service/#step-31-create-a-manual-trigger-for-the-tcp-client","title":"Step 3.1: Create a manual trigger for the TCP client","text":"

    To create a manual task component, follow these steps:

    1. On the Choreo Console header, click the Project list and select the project where you created the TCP service component. This opens the project home page.
    2. Go to the Component Listing section and click + Create.
    3. Click the Manual Task card.

    4. Enter a display name, a unique name, and a description for the component. You can enter the values given below:

      Info

      In the Component Name field, you must specify a name to uniquely identify the component in various contexts. The value is editable only at the time you create the component. You cannot change the name after you create the component.

      Field Value Component Display Name Go TCP Client Component Name go-tcp-client Description Receive greetings

    5. Click the GitHub tab.

    6. To allow Choreo to connect to your GitHub account, click Authorize with GitHub. If you have not already connected your GitHub repository to Choreo, enter your GitHub credentials and select the repository you created in the prerequisites section to install the Choreo GitHub App.

      Alternatively, you can paste the Choreo samples repository URL in the Provide Repository URL field to connect to it without requiring authorization from the Choreo Apps GitHub application. However, authorizing the repository with the Choreo GitHub App is necessary if you want to enable Auto Deploy for the component.

      Note

      The Choreo GitHub App requires the following permissions:

      • Read and write access to code and pull requests.
      • Read access to issues and metadata.

      You can revoke access if you do not want Choreo to have access to your GitHub account. However, write access is exclusively utilized for sending pull requests to a user repository. Choreo will not directly push any changes to a repository.

    7. Under Connect Your Repository, enter the following information:

      Field Value Organization Your GitHub account GitHub Repository choreo-samples Branch main

    8. Select Docker as the buildpack.

    9. Enter the following information:

      Field Value Docker Context docker-tcp-service Dockerfile docker-tcp-service/Dockerfile.client

    10. Click Create. This creates the component and takes you to the Overview page of the component.

    "},{"location":"develop-components/develop-services/expose-a-tcp-server-via-a-service/#step-32-build-the-tcp-client-component","title":"Step 3.2: Build the TCP client component","text":"

    To build the component, follow these steps:

    1. In the left navigation menu, click Build.

    2. On the Build page, click Build Latest.

      Note

      Building the service component may take a while. You can track the progress via the logs in the Build Details pane. Once the build process is complete, the build status changes to Success.

    "},{"location":"develop-components/develop-services/expose-a-tcp-server-via-a-service/#step-33-setup-environment-variables-and-deploy-the-tcp-client","title":"Step 3.3: Setup environment variables and deploy the TCP client","text":"

    The client application, in this case, the TCP client, requires the server URL of the TCP server service. This is read from the client application as an environment variable. Follow the steps below to configure the environment variable for the client application:

    1. On the Choreo Console left navigation menu, click Deploy.
    2. In the Set Up card, click Configure & Deploy.
    3. In the Environment Configurations pane that opens, click + Add.

    4. Specify the following name and value to configure the environment variable for the client application:

      Field Value Name SERVER_ADDRESS Value Paste the URL value copied after deploying the TCP service via step 2.2 above. Make sure to drop the tcp:// part and the trailing / from the URL when copying. For example, add only go-tcp-server-1097922445:8080.

    5. Click Add and then click Next.

    6. Click Deploy.
    "},{"location":"develop-components/develop-services/expose-a-tcp-server-via-a-service/#step-34-execute-the-tcp-client-component","title":"Step 3.4: Execute the TCP client component","text":"

    To execute the TCP client, follow these steps:

    1. In the left navigation menu, click Execute.
    2. Click Run Now. This triggers the TCP client and generates logs. You can trigger multiple runs to generate multiple logs.

    For details on what you can monitor via the execute page, see Monitor executions.

    "},{"location":"develop-components/develop-services/expose-a-udp-server-via-a-service/","title":"Expose a UDP Server via a Service","text":"

    Choreo offers the flexibility to design and deploy applications in the programming language of your choice. One compelling choice for certain network communication needs is UDP (User Datagram Protocol). UDP is a high-speed, connectionless protocol ideal for scenarios where lightweight, real-time data transmission is essential.

    In this guide, you will learn to use Choreo to create a Service component that exposes a UDP server implemented in Go, enabling efficient and scalable communication with any UDP client application. No prior knowledge of the Go language is necessary to follow this guide.

    By following this guide, you will:

    • Setup a UDP server
      • Create a simple UDP server using a Service component.
      • Link the containerized UDP service to the Choreo component using the Dockerfile.
      • Deploy the UDP server component in Choreo.
    • Setup a UDP client
      • Create a UDP client using a manual task component.
      • Link the containerized UDP client to the Choreo component using the Dockerfile.
      • Deploy the UDP client component in Choreo.
    • Invoke the UDP server using a UDP client and check the response through the Choreo log view.
    "},{"location":"develop-components/develop-services/expose-a-udp-server-via-a-service/#prerequisites","title":"Prerequisites","text":"

    Before you try out this guide, complete the following:

    • If you are signing in to the Choreo Console for the first time, create an organization as follows:

      1. Go to https://console.choreo.dev/, and sign in using your preferred method.
      2. Enter a unique organization name. For example, Stark Industries.
      3. Read and accept the privacy policy and terms of use.
      4. Click Create.

      This creates the organization and opens the Project Home page of the default project created for you.

    • Fork the Choreo samples repository, which contains the sample service implementation for this guide.

    Let's get started!

    "},{"location":"develop-components/develop-services/expose-a-udp-server-via-a-service/#learn-the-repository-file-structure","title":"Learn the repository file structure","text":"

    It is important to understand the purpose of the key files in the sample service. The following table provides a brief overview of each file in the sample service.

    Note

    The following file paths are relative to the path <sample-repository-dir>/docker-udp-service.

    File Path Description server/main.go The greeter service code written in the Go language. client/main.go The greeter client application written in the Go language. Dockerfile.server The Dockerfile to build the container image of the server application. Dockerfile.client The Dockerfile to build the container image of the client application. .choreo/endpoints.yaml The Choreo-specific configuration provides information about how Choreo exposes the service."},{"location":"develop-components/develop-services/expose-a-udp-server-via-a-service/#configure-the-service-port-with-endpoints","title":"Configure the service port with endpoints","text":"

    In Choreo, you can expose your services via endpoints.

    Let's run the UDP server service component on port 5050. To securely expose the service through Choreo, you must provide the port and other required information to Choreo. For detailed information on each attribute of an endpoint, see Configure Endpoints.

    Choreo looks for an endpoints.yaml file inside the .choreo directory to configure the endpoint details of a containerized component. Place the .choreo directory at the root of the Docker build context path.

    In our gRPC server sample, the endpoints.yaml file is at docker-udp-service/.choreo/endpoints.yaml, where the build context path is docker-udp-service.

    "},{"location":"develop-components/develop-services/expose-a-udp-server-via-a-service/#step-1-create-a-service-component-with-a-udp-endpoint","title":"Step 1: Create a service component with a UDP endpoint","text":"

    To create a containerized service component, follow these steps:

    1. Go to https://console.choreo.dev/ and sign in. This opens the project home page.
    2. If you already have one or more components in your project, click + Create. Otherwise, proceed to the next step.
    3. Click the Service card.

    4. Enter a display name, a unique name, and a description for the service component. You can enter the values given below:

      Info

      In the Component Name field, you must specify a name to uniquely identify the component in various contexts. The value is editable only at the time you create the component. You cannot change the name after you create the component.

      Field Value Component Display Name Go UDP Server Component Name go-udp-server Description Send greetings

    5. Click the GitHub tab.

    6. To allow Choreo to connect to your GitHub account, click Authorize with GitHub. If you have not already connected your GitHub repository to Choreo, enter your GitHub credentials and select the repository you created in the prerequisites section to install the Choreo GitHub App.

      Alternatively, you can paste the Choreo samples repository URL in the Provide Repository URL field to connect to it without requiring authorization from the Choreo Apps GitHub application. However, authorizing the repository with the Choreo GitHub App is necessary if you want to enable Auto Deploy for the component.

      Note

      The Choreo GitHub App requires the following permissions:

      • Read and write access to code and pull requests.
      • Read access to issues and metadata.

      You can revoke access if you do not want Choreo to have access to your GitHub account. However, write access is exclusively utilized for sending pull requests to a user repository. Choreo will not directly push any changes to a repository.

    7. Under Connect Your Repository, enter the following information:

      Field Value Organization Your GitHub account GitHub Repository choreo-samples Branch main

    8. Select Docker as the buildpack.

    9. Enter the following information:

      Field Value Docker Context docker-udp-service Dockerfile docker-udp-service/Dockerfile.server

      Info

      1. To successfully build your container with Choreo, it is essential to explicitly define a User ID (UID) under the USER instruction in your Dockerfile. For reference, see the sample Dockerfile. To ensure that the defined USER instruction is valid, it must conform to the following conditions:

        • A valid User ID is a numeric value between 10000-20000, such as 10001 or 10500.
        • Usernames are considered invalid and should not be used. For example, my-custom-user-12221 or my-custom-user are invalid User IDs.

      2. The Dockerfile utilized in this guide is a multi-stage Dockerfile, which is designed to keep the final image size small and provides the ability to build the application with a specific version of tools and libraries.

    10. Click Create. This creates the component and takes you to the Overview page of the component.

    You have successfully created a service from a Dockerfile. Next, you can build and deploy the service.

    "},{"location":"develop-components/develop-services/expose-a-udp-server-via-a-service/#step-2-build-and-deploy","title":"Step 2: Build and deploy","text":"

    Now that you have connected the source repository, and configured the endpoint details, it's time to build the service and create an image. Then you can deploy the image and test the service.

    "},{"location":"develop-components/develop-services/expose-a-udp-server-via-a-service/#step-21-build","title":"Step 2.1: Build","text":"

    To build the service, follow these steps:

    1. In the left navigation menu, click Build.

    2. On the Build page, click Build Latest.

      Note

      Building the service component may take a while. You can track the progress via the logs in the Build Details pane. Once the build process is complete, the build status changes to Success.

      You can access the following scans under Build.

      • The Dockerfile scan: Choreo performs a scan to check if a non-root user ID is assigned to the Docker container to ensure security. If no non-root user is specified, the build will fail.
      • Container (Trivy) vulnerability scan: This detects vulnerabilities in the final docker image.

      • Container (Trivy) vulnerability scan: The details of the vulnerabilities open in a separate pane. If this scan detects critical vulnerabilities, the build will fail.

        Info

        If you have Choreo environments on a private data plane, you can ignore these vulnerabilities and proceed with the deployment.

    "},{"location":"develop-components/develop-services/expose-a-udp-server-via-a-service/#step-22-deploy","title":"Step 2.2: Deploy","text":"

    To deploy the service, follow these steps:

    1. In the left navigation menu, click Deploy.
    2. On the Set Up card, click Configure & Deploy.
    3. In the Environment Configurations pane that opens, click Next to skip the configuration.
    4. In the File Mount pane, click Next to skip the configuration.

    5. Review the Endpoint Details and click Deploy.

      Note

      Deploying the service component may take a while. Once deployed, the Development environment card indicates the Deployment Status as Active.

    6. Once you have successfully deployed your service, navigate to the component overview page and copy the UDP service address. You must provide that address when setting up the client application later in this guide.

    You have successfully deployed the UDP server. Currently, the UDP service is only accessible by the components deployed within the same project.

    "},{"location":"develop-components/develop-services/expose-a-udp-server-via-a-service/#step-3-invoke-the-udp-service","title":"Step 3: Invoke the UDP service","text":"

    Now let's use a UDP client to invoke the UDP service that you created above. To do this, you can create a manual trigger component as the UDP client. This is the recommended approach because, in this example, it's more efficient to have a client that connects to the server, sends a request, and then stops. Here, a continuously executing task isn't required. Furthermore, if you use a manual trigger component, you won't need to expose an endpoint in the client for invocation, unlike with an API.

    "},{"location":"develop-components/develop-services/expose-a-udp-server-via-a-service/#step-31-create-a-manual-trigger-for-the-udp-client","title":"Step 3.1: Create a manual trigger for the UDP client","text":"

    To create a manual task component, follow these steps:

    1. On the Choreo Console header, click the Project list and select the project where you created the UDP service component. This opens the project home page.
    2. Go to the Component Listing section and click + Create.
    3. Click the Manual Task card.

    4. Enter a display name, a unique name, and a description for the component. You can enter the values given below:

      Info

      In the Component Name field, you must specify a name to uniquely identify the component in various contexts. The value is editable only at the time you create the component. You cannot change the name after you create the component.

      Field Value Component Display Name Go UDP Client Component Name go-udp-client Description Receive greetings

    5. Click the GitHub tab.

    6. To allow Choreo to connect to your GitHub account, click Authorize with GitHub. If you have not already connected your GitHub repository to Choreo, enter your GitHub credentials and select the repository you created in the prerequisites section to install the Choreo GitHub App.

      Alternatively, you can paste the Choreo samples repository URL in the Provide Repository URL field to connect to it without requiring authorization from the Choreo Apps GitHub application. However, authorizing the repository with the Choreo GitHub App is necessary if you want to enable Auto Deploy for the component.

      Note

      The Choreo GitHub App requires the following permissions:

      • Read and write access to code and pull requests.
      • Read access to issues and metadata.

      You can revoke access if you do not want Choreo to have access to your GitHub account. However, write access is exclusively utilized for sending pull requests to a user repository. Choreo will not directly push any changes to a repository.

    7. Under Connect Your Repository, enter the following information:

      Field Value Organization Your GitHub account GitHub Repository choreo-samples Branch main

    8. Select Docker as the buildpack.

    9. Enter the following information:

      Field Value Docker Context docker-udp-service Dockerfile docker-udp-service/Dockerfile.client

    10. Click Create. This creates the component and takes you to the Overview page of the component.

    "},{"location":"develop-components/develop-services/expose-a-udp-server-via-a-service/#step-32-build-the-udp-client-component","title":"Step 3.2: Build the UDP client component","text":"

    To build the component, follow these steps:

    1. In the left navigation menu, click Build.

    2. On the Build page, click Build Latest.

      Note

      Building the service component may take a while. You can track the progress via the logs in the Build Details pane. Once the build process is complete, the build status changes to Success.

    "},{"location":"develop-components/develop-services/expose-a-udp-server-via-a-service/#step-33-setup-environment-variables-and-deploy-the-udp-client","title":"Step 3.3: Setup environment variables and deploy the UDP client","text":"

    The client application, in this case, the UDP client, requires the server URL of the UDP server service. This is read from the client application as an environment variable. Follow the steps below to configure the environment variable for the client application:

    1. On the Choreo Console left navigation menu, click Deploy.
    2. In the Set Up card, click Configure & Deploy.
    3. In the Environment Configurations pane that opens, click + Add.

    4. Specify the following name and value to configure the environment variable for the client application:

      Field Value Name SERVER_ADDRESS Value Paste the URL value copied after deploying the UDP service via step 2.2 above. Make sure to drop the udp:// part and the trailing / from the URL when copying. For example, add only go-udp-server-1097922445:8080.

    5. Click Add and then click Next.

    6. Click Deploy.
    "},{"location":"develop-components/develop-services/expose-a-udp-server-via-a-service/#step-34-execute-the-udp-client-component","title":"Step 3.4: Execute the UDP client component","text":"

    To execute the UDP client, follow these steps:

    1. In the left navigation menu, click Execute.
    2. Click Run Now. This triggers the UDP client and generates logs. You can trigger multiple runs to generate multiple logs.

    For details on what you can monitor via the execute page, see Monitor executions.

    "},{"location":"develop-components/develop-services/service-component-overview/","title":"Service Component Overview","text":"

    Explore how to create, deploy, manage, and observe service components in Choreo.

    "},{"location":"develop-components/develop-services/service-component-overview/#what-is-a-service-component","title":"What is a service component?","text":"

    A service component in Choreo lets you deploy and expose REST, GraphQL, gRPC, UDP, or TCP services. It is a fundamental building block for creating cloud-native applications in Choreo. They provide a simple and effective way to expose functionality as a service to other components within Choreo or to the outside world.

    Service components encapsulate business logic and provide standardized interfaces, called endpoints, for communicating with other components or systems. You can deploy and scale services independently, which makes them highly flexible and adaptable to changing workloads.

    With the help of the service component, developers can quickly create APIs and microservices, making it easier to implement and manage complex software systems. Service components can also be integrated with other Choreo components, that acts as message processors, connectors, and data sources, etc to create powerful end-to-end solutions.

    Services and integrations are exposed to other services, integrations, or applications through endpoints. A service or an integration can expose multiple endpoints, each representing a unique entry point into the service. For example, a service may expose a REST API endpoint and a GraphQL endpoint, each providing different ways to interact with the service. Endpoints provide specific details for how the service or the integration can be consumed. For instance, the port number, protocol, and the schema such as open API specification (OAS) or GraphQL schema. By defining these details, endpoints make it possible for other services, integrations, and applications to discover and interact with the service in a standardized way.

    Choreo defines endpoints by combining port binding, protocol, endpoint name, network visibility, endpoint schema, and additional protocol-related fields. The following table describes each attribute of an endpoint.

    Field Description Name A unique identifier for the endpoint within the service component. Port The network port on which the endpoint is accessible. Type The endpoint protocol. Supported protocols: REST, GraphQL, gRPC, UDP, and TCP. Network Visibility Determines the level of visibility of an endpoint. Possible values are:
    • Project: Allows components within the same project to access the endpoint.
    • Organization: Allows any component within the same organization to access the endpoint but restricts access to components outside the organization.
    • Public: Allows any client to access the endpoint, regardless of location or organization.
    Schema Specifies the structure and format of the data exchanged through the endpoint. Context (HTTP and GraphQL only) A context path that you add to the endpoint's URL for routing purposes."},{"location":"develop-components/develop-services/service-component-overview/#configure-endpoints","title":"Configure endpoints","text":"

    The method of defining endpoints depends on the buildpack. For buildpacks other than Ballerina and WSO2 MI, it is required to have an endpoints.yaml file in project root directory to create the Service component.

    "},{"location":"develop-components/develop-services/service-component-overview/#configure-endpoints-with-buildpacks-except-ballerina","title":"Configure endpoints with buildpacks (except Ballerina)","text":"

    When you build a service component using any other buildpacks(Java, Python, NodeJS, Ruby, PHP, Go, Dockerfile, etc) other than Ballerina and WSO2 MI, you can configure the endpoint details with the endpoints.yaml configuration file. You must place this file inside the .choreo directory at the build context path and commit it to the source repository.

    See Understanding the endpoints.yaml file to learn about the endpoints.yaml file.

    "},{"location":"develop-components/develop-services/service-component-overview/#configure-endpoints-with-the-ballerina-buildpack","title":"Configure endpoints with the Ballerina buildpack","text":"

    When you create a service component with the Ballerina buildpack, Choreo automatically detects the endpoint details for REST APIs. You can override the auto-generated endpoint configuration by providing the endpoints.yaml file in the source directory.

    Note

    Automatic endpoint generation is not supported for dynamic endpoint parameters such as variable ports. Therefore, you must use an endpoint.yaml file to define dynamic endpoint parameters.

    See Understanding the endpoints.yaml file to learn about the endpoints.yaml file.

    "},{"location":"develop-components/develop-services/service-component-overview/#learn-the-endpointsyaml-file","title":"Learn the endpoints.yaml file","text":"

    The endpoints.yaml file has a specific structure and contains the following details:

    Field 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. type Required The type of traffic this endpoint is accepting, such as REST, GraphQL, gRPC, UDPor 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. 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. Sample endpoints.yaml

    File location:

    <docker-build-context-path>/.choreo/endpoints.yaml\n

    Note

    • For components built with Ballerina buildpack docker-build-context-path should be replaced with component-root. For example: <component-root>/.choreo/endpoints.yaml

    • For components built with WSO2 MI buildpack docker-build-context-path should be replaced with <Project Path>. For example: <Project Path>/.choreo/endpoints.yaml

    File content:

    # +required Version of the endpoint configuration YAML\nversion: 0.1\n# +required List of endpoints to create\nendpoints:\n# +required Unique name for the endpoint. (This name will be used when generating the managed API)\n- name: Greeting Service\n# +required Numeric port value that gets exposed via this endpoint\nport: 9090\n# +required Type of the traffic this endpoint is accepting. Example: REST, GraphQL, etc.\n# Allowed values: REST, GraphQL, GRPC, UDP, TCP\ntype: REST\n# +optional Network level visibility of this endpoint. Defaults to Public\n# Accepted values: Project|Organization|Public.\nnetworkVisibility: Project\n# +optional Context (base path) of the API that is exposed via this endpoint.\n# This is mandatory if the endpoint type is set to REST or GraphQL.\ncontext: /greeting\n# +optional Path to the schema definition file. Defaults to wild card route if not provided\n# This is only applicable to REST endpoint types.\n# The path should be relative to the docker context.\nschemaFilePath: greeting_openapi.yaml\n
    "},{"location":"develop-components/develop-services/service-component-overview/#apply-advanced-component-connection-configurations","title":"Apply advanced component connection configurations","text":"

    The component-config.yaml file extends the capabilities of endpoints.yaml by introducing enhancements that allow you to apply advanced inbound and outbound connection configurations.

    Beta release

    • The current version of the component-config.yaml file is considered stable. However, it is important to note that the configuration schema may undergo changes and improvements based on user feedback.
    • Support for the current schema will remain even when new versions are introduced.

    The component-config.yaml file complements and enhances the existing endpoint configuration process. It allows you to define how your service's endpoints (inbound connections) are exposed and how your service connects to external services or components (outbound connections).

    • Inbound configurations: This configuration section is for you to define inbound connections, Similar to endpoints.yaml, you can define how your service endpoints are exposed. It aligns seamlessly with the existing endpoint schema structure.

    • Outbound configurations: This configuration section is for you to specify outbound connection details, including service connections. The Choreo Internal Marketplace facilitates creating connections with existing services. To learn more about Choreo Marketplace, see Choreo Marketplace.

    Note

    • If both component-config.yaml and endpoints.yaml are defined in the .choreo path, the component-config.yaml file takes priority.
    • Outbound connections are not supported for deprecated components and WSO2 MI buildpack components.
    "},{"location":"develop-components/develop-services/service-component-overview/#learn-the-component-configyaml-file","title":"Learn the component-config.yaml file","text":"

    The component-config.yaml file has a specific structure and contains the following details:

    Field Required Description apiVersion Required The version of the component-config.yaml file defaults to core.choreo.dev/v1beta1. kind Required The resource type of the file defaults to ComponentConfig. spec.inbound Optional The list of inbound connection configurations. spec.outbound Optional The list of outbound connection configurations. Inbound connection configurations (spec.inbound)

    In the spec.inbound configuration section, you can specify endpoints to set up inbound connections. To specify endpoints, you can follow the existing endpoints schema structure. For details on the endpoints schema structure, see the endpoints schema documentation.

    Outbound connection configurations (spec.outbound)

    In the spec.outbound section, you can define serviceReferences. To define serviceReferences, you can use the service references generated in the Internal Marketplace when creating a service connection. To copy the outbound connection configurations, see the inline developer guide that is available when you create a connection.

    The serviceReferences schema has a specific structure and contains the following details:

    Field Required Description name Required A unique name for the service reference. connectionConfig Required A unique name for the connection instance. env Optional The list of environment variable mappings that get injected into the container. env.from Required The key name of the connection configuration. env.to Required The environment variable that gets injected into the container.

    Note

    Choreo automatically generates outbound connection configurations upon the creation of a connection within the internal marketplace. The properties such as name, connectionConfig, and env.from are automatically generated. However, you must manually set the env.to value.

    Sample component-config.yaml

    File location:

    <docker-build-context-path>/.choreo/component-config.yaml\n

    Note

    • For components built using the Ballerina buildpack, you must replace docker-build-context-path with the component-root. For example, <component-root>/.choreo/component-config.yaml.
    • For components built using the WSO2 MI buildpack, you must replace docker-build-context-path with the <Project Path>. For example, <Project Path>/.choreo/component-config.yaml.

    File content:

    apiVersion: core.choreo.dev/v1beta1\nkind: ComponentConfig\nspec:\n# +optional Incoming connection details for the component (AKA endpoints).\ninbound:\n# +required Unique name for the endpoint. (This name will be used when generating the managed API)\n- name: Greeting Service\n# +required Numeric port value that gets exposed via the endpoint\nport: 9090\n# +required Type of traffic that the endpoint is accepting. For example: REST, GraphQL, etc.\n# Allowed values: REST, GraphQL, GRPC, TCP, UDP.\ntype: REST\n# +optional Network level visibility of the endpoint. Defaults to Public\n# Accepted values: Project|Organization|Public.\nnetworkVisibility: Public\n# +optional Context (base path) of the API that gets exposed via the endpoint.\n# This is mandatory if the endpoint type is set to REST or GraphQL.\ncontext: /greeting\n# +optional The path to the schema definition file. Defaults to wildcard route if not specified.\n# This is only applicable to REST endpoint types.\n# The path should be relative to the Docker context.\nschemaFilePath: greeting_openapi.yaml\n# +optional Outgoing connection details for the component.\noutbound:\n# +optional Defines the service references from the Internal Marketplace.\nserviceReferences:\n# +required Name of the service reference.\n- name: choreo:///apifirst/mttm/mmvhxd/ad088/v1.0/PUBLIC\n# +required Name of the connection instance.\nconnectionConfig: 19d2648b-d29c-4452-afdd-1b9311e81412\n# +optional Environment variables injected to the component for connection configuration.\nenv:\n# +required Key name of the connection configuration.\n- from: ServiceURL\n# +required Environment variable injected to the container.\nto: SERVICE_URL\n
    "},{"location":"develop-components/develop-services/service-component-overview/#expose-endpoints-as-managed-apis","title":"Expose endpoints as managed APIs","text":"

    Exposing endpoints as managed APIs is crucial to ensure secure and controlled access to the services being exposed. When a user wants to expose their written service to the outside world or to the organization at large, there is an inherent security risk involved. To mitigate this risk, the Choreo platform is built with an internal (access within the organization only) or external (publicly accessible) gateway that is protected with Choreo API management making the services secure by design.

    Note

    This feature is not available for gRPC, UDP, and TCP endpoints.

    If you want to expose an endpoint as a managed API in Choreo, you need to set the network visibility to either Organization or Public. This allows the endpoint to be exposed through the Choreo API Gateway, which provides a number of benefits, including:

    • Expose APIs to external and internal consumers
    • Full lifecycle API Management
    • API throttling
    • Secure APIs with industry-standard authorization flows
    • API analytics and monitoring

    Once you deploy the service component, Choreo will expose the endpoint as a managed API through the Choreo API Gateway. You can then use the full lifecycle API management features provided by Choreo to test, deploy, maintain, monitor, and manage your API using the API management features.

    "},{"location":"develop-components/develop-services/service-component-overview/#understand-the-default-component-url","title":"Understand the default component URL","text":"

    The default URL of a component corresponds to the default endpoint of the component and is structured as follows:

    <domain>/<project-name>/<component-name>

    This URL does not include the default endpoint name. For all other endpoints, the URL structure includes the endpoint name, as follows:

    <domain>/<project-name>/<component-name>/<endpoint-name>

    If a component has multiple endpoints, Choreo allows you to change the endpoint corresponding to the default component URL. For a component with a single endpoint, the default URL automatically corresponds to that endpoint.

    "},{"location":"develop-components/develop-services/service-component-overview/#change-the-default-endpoint-of-a-component","title":"Change the default endpoint of a component","text":"

    To change the default endpoint of a component, follow the steps given below:

    Note

    • You cannot change the default endpoint if it has associated published APIs. You must go to the Lifecycle page and unpublish the relevant APIs before updating the default endpoint. For instructions on unpublishing an API, see Lifecycle Management.
    • Choreo does not allow you to change the default endpoint of a component if you create multiple deployment tracks within its current major version, or promote the component beyond its initial environment.
    1. Sign in to the Choreo Console.
    2. In the Component Listing pane, click on the component for which you want to change the default endpoint.
    3. In the left navigation menu, click Deploy.
    4. On the Deploy page, go to the Set Up card and click Configure & Deploy.
    5. In the Environment Configurations pane that opens, click Next.
    6. In the File Mount pane that opens, click Next.
    7. In the Endpoint Details pane that opens, click the Default Endpoint list, select the endpoint you want to set as the default endpoint, and then click Update.
    8. Click Deploy. This deploys the component with the selected endpoint as the default, and the default URL will now correspond to this endpoint.
    "},{"location":"develop-components/develop-web-applications/build-and-deploy-a-single-page-web-application/","title":"Build and Deploy a Single-Page Web Application","text":"

    A web application is an application program hosted on a server and serves ingress traffic through a browser. In Choreo, you can deploy a web application by creating a Web Application component and connecting it to a Git repository that contains the implementation of the web application. Web applications can fall into one of the following categories:

    • Single page applications (SPAs): Examples include React, Angular, Vue, Svelte, etc.
    • Web servers: These serve static content or provide server-side rendering/static site generation (SSR/SSG).
    • Static content: Examples include websites and other static resources that do not require a backend, usually comprising static HTML/JS/CSS files.
    "},{"location":"develop-components/develop-web-applications/build-and-deploy-a-single-page-web-application/#prerequisites","title":"Prerequisites","text":"
    • To deploy a Web Application component, you must have a GitHub account with a repository containing the web application's implementation. For this guide, fork the https://github.com/wso2/choreo-samples repository, which contains the sample web application implementation.
    "},{"location":"develop-components/develop-web-applications/build-and-deploy-a-single-page-web-application/#create-a-web-application","title":"Create a web application","text":"

    You can create a web application in Choreo as follows:

    • Build and deploy a SPA from the source code.

      • Create a Web Application component by connecting a repository that includes the web application source code.
      • Select the relevant buildpack. Default buildpacks include React, Angular, and Vue.js. If you are using a different SPA framework, you can try one of these buildpacks because the configurations can be overridden to support most Javascript-based SPAs.
      • Enter the build command based on your package manager. NPM, yarn, and pnpm are supported and the relevant package manager is run based on the dependency lock file in your repository (defaults to NPM if no lock file is present).
      • Specify the build output directory.
      • Specify the NodeJS version. Choreo does not pick the Nodejs version from the package.json engine property. The required Node version must be explicitly set in the build configuration.

      Once you create the Web Application component, Choreo automatically generates a build pipeline for your single-page application and deploys it.

    • Bring your Dockerfile.

      • Create a Web Application component by connecting a repository that contains the Dockerfile for your containerized web application.
      • Commit a Dockerfile to your connected git repository to have full control over your build process.

      This approach is recommended if you are deploying a web server and not just a single-page application (or a single-page application with a complex build process).

    • Host static websites.

      • To host static web content, you can create a Web Application component and connect it to the GitHub repository that contains the required static assets.
      • Select the Static Websites buildpack. This buildpack does not trigger a build process. It only fetches the files from the path specified in the repository and serves as it is.

    Now let's take a look at how you can build and deploy a SPA from source code:

    Follow the steps below to create a sample Web Application component and deploy it in Choreo:

    1. Sign in to the Choreo Console at https://console.choreo.dev/login/. This opens the Project Home page.
    2. If you already have one or more components in your project, click + Create. Otherwise, proceed to the next step.
    3. Click the Web Application card.
    4. This opens the Create a Web Application pane, where you can specify a name and description for the component. Enter a unique name and description.
    5. Go to the GitHub tab.

    6. To allow Choreo to connect to your GitHub account, click Authorize with GitHub. If you have not already connected your GitHub repository to Choreo, enter your GitHub credentials and select the repository you created in the prerequisites section to install the Choreo GitHub App.

      Alternatively, you can paste the Choreo samples repository URL in the Provide Repository URL field to connect to it without requiring authorization from the Choreo Apps GitHub application. However, authorizing the repository with the Choreo GitHub App is necessary if you want to enable Auto Deploy for the component.

      Note

      The Choreo GitHub App requires the following permissions:

      • Read and write access to code and pull requests.
      • Read access to issues and metadata.

      You can revoke access if you do not want Choreo to have access to your GitHub account. However, write access is exclusively utilized for sending pull requests to a user repository. Choreo will not directly push any changes to a repository.

    7. Enter the following information:

      Field Description GitHub Account Your account GitHub Repository choreo-samples Branch main

    8. Select React as the Buildpack.

    9. Enter the following information:

      Field Description Project Directory /react-single-page-app Build Command npm run build Build Path build Node Version 18

      Tip

      Managed authentication is enabled by default when you create a web application using React, Angular, or Vue.js buildpacks. To learn how to set up authentication for your web application with Choreo's managed authentication, see Secure Web Applications with Managed Authentication.

    10. Click Create. Choreo initializes the component with the sample implementation and opens the Overview page of the component.

    You have successfully created a Web Application component from the source code. Now let's build and deploy the web application.

    "},{"location":"develop-components/develop-web-applications/build-and-deploy-a-single-page-web-application/#build-your-web-application","title":"Build your web application","text":"

    To build the web application, follow the steps given below:

    1. In the left navigation menu, click Build.
    2. In the Builds pane, click Build. This opens the Commits pane, where you can see all the commits related to the component.

    3. Select the latest commit and click Build. This triggers the build process and displays the progress in the Build Logs pane.

      You can access the following scans in the Build Logs pane:

      • The Dockerfile scan: Choreo performs a scan to check if a non-root user ID is assigned to the Docker container to ensure security. If no non-root user is specified, the build will fail.
      • Container (Trivy) vulnerability scan: This detects vulnerabilities in the final docker image.
      • Container (Trivy) vulnerability scan: The details of the vulnerabilities open in a separate pane. If this scan detects critical vulnerabilities, the build will fail.

      Info

      If you have Choreo environments on a private data plane, you can ignore these vulnerabilities and proceed with the deployment.

      Note

      The build process can take a while to complete. When the build process is complete, the build will be listed in the Builds pane along with its status.

    Here, you will see the build status as Success.

    "},{"location":"develop-components/develop-web-applications/build-and-deploy-a-single-page-web-application/#deploy-and-access-your-web-application","title":"Deploy and access your web application","text":"
    1. In the left navigation menu, click Deploy.
    2. In the Set Up card, click Configure and Deploy. This opens the Configure & Deploy pane, where you can add a file mount if necessary. In this guide, you will not add a file mount.
    3. Click Next. This takes you to the Authentication Settings pane.

    4. Keep the default settings and click\u00a0Deploy.

      Note

      • The deployment process can take a few minutes to complete. On successful deployment, you will see the\u00a0Deployment Status\u00a0as\u00a0Active\u00a0in the\u00a0Development\u00a0card.

    5. To verify that you have successfully hosted the web application, click the\u00a0Web App URL\u00a0in the\u00a0Development\u00a0card. This takes you to the web application.

    "},{"location":"develop-components/develop-web-applications/build-and-deploy-a-single-page-web-application/#create-a-short-url-for-your-web-application-in-production","title":"Create a short URL for your web application in production","text":"

    Info

    This feature is only available on the Choreo cloud data plane.

    When you promote your component to the Production environment, you have the option to create a personalized short URL for your web application. The URL follows the https://{your-short-prefix}.choreoapps.dev structure, where you can select a name of your preference for {your-short-prefix}.

    To create a short URL for your web application, follow the steps given below:

    1. Click Promote in the Development card and promote your web application to production.
    2. In the Production card, click Create a short URL.

    3. Specify a Short URL prefix of your choice and click Save.

      Note

      Short URL names/prefixes are subject to availability, provided on a first-come-first-serve basis.

    "},{"location":"develop-components/develop-web-applications/build-and-deploy-a-single-page-web-application/#manage-runtime-configurations-for-web-applications","title":"Manage runtime configurations for web applications","text":"

    For web applications with a backend server, Choreo allows you to mount runtime configurations and secrets as environment variables and/or file mounts for a specific environment. Alternatively, you can also inject them into the client application during server-side rendering or when serving static content.

    However, in the case of SPAs that run completely on the browser, Choreo does not support baking-in environment variables or other configurations. This is because Choreo follows a multi-environment deployment model, where configuration should be kept separate from the build and injected at runtime. For example, in most React SPA frameworks, the process.env stub is available during build time. However, it does not actually read in variables from the runtime. Instead, it is baked into the final JavaScript output during the build process.

    To manage runtime configurations, Choreo recommends the following approach (although this is a React example, the approach is generally applicable to other SPA frameworks as well).

    Note

    • With SPAs, anything you mount as a runtime config will be available to your users in the browser.
    • Do not include sensitive secrets that are not browser-safe.

    Follow the steps given below to manage runtime configurations for the React application you created above:

    1. Go to your forked Choreo samples repository.
    2. Open the public directory.

    3. Create and commit a new file named config.js in the public directory of your React application. This file should contain the runtime configuration variables you want to expose to your application, such as API endpoints or feature flags. Let's expose the API URL and a feature flag as follows:

      window.config = {\napiUrl: 'https://api.example.com',\n    featureFlags: {\n        enableNewFeature: true,\n        enableExperimentalFeature: false,\n    },\n};\n
      4. In your index.html file inside the public directory, add a script tag as follows to include the config.js file inside the tag. The config.js file will be accessible via JavaScript at runtime. 

      <!DOCTYPE html>\n<html lang=\"en\">\n<head>\n    <meta charset=\"utf-8\" />\n    <title>My React App</title>\n</head>\n<body>\n    <div id=\"root\"></div>\n    <script src=\"%PUBLIC_URL%/config.js\"></script>\n</body>\n</html>\n
      This makes the window.config object available to your app at runtime.

    4. In your React component, you can access the configuration variables by referencing the window.config object as follows:

      import React from 'react';\n\nfunction MyComponent() {\nconst apiUrl = window.config.apiUrl;\nconst enableNewFeature = window.config.featureFlags.enableNewFeature;\nconst enableExperimentalFeature = window.config.featureFlags.enableExperimentalFeature;\n\n// ...\n}\n
      Now you can deploy your component.

    5. When you deploy your component to Choreo, create a config file mount in the specified path for each environment (where your index.html expects the config.js file as in this example). https://wso2.com/choreo/docs/devops-and-ci-cd/manage-configurations-and-secrets/#apply-a-file-mount-to-your-container.

      6. "},{"location":"develop-components/develop-web-applications/build-and-deploy-a-single-page-web-application/#limitations","title":"Limitations","text":"

      The following limitations are specific to the Choreo cloud data plane:

      • Request size limit, including headers, cookies, and payloads: 256KB
      • Response body size limit: 20MB
      • Only one open port is permitted per web application. While you can have multiple ports open for project-level communication within a data plane, incoming traffic from the internet can only be directed to one port. This differs from the Service type components, which support multiple endpoints.
      "},{"location":"develop-components/develop-web-applications/build-and-deploy-a-single-page-web-application/#troubleshoot-a-web-application","title":"Troubleshoot a web application","text":"

      • I\u2019m seeing a blank page or a 502 error after I deploy my web application

        If you encounter a blank page or a 502 error after deploying your web application, it typically indicates that the wrong directory is being served. To resolve this issue, follow these steps:

        • Double-check the build output directory, especially if you are using a Dockerfile-less buildpack. Ensure that the specified output directory matches the actual output directory generated during the build process. For example, if you have erroneously entered public/ as the output directory when it should have been build/.

        By verifying and correcting the output directory alignment, you should be able to address the issue of encountering a blank page or experiencing a 502 error on deploying your web application.

      "},{"location":"develop-components/develop-web-applications/develop-web-applications-locally-with-managed-authentication/","title":"Develop Web Applications Locally with Choreo\u2019s Managed Authentication","text":"

      Choreo\u2019s managed authentication capability exposes a set of backend for frontend (BFF) endpoints, facilitating authentication and authorization for web applications. These endpoints are readily available for single-page web applications deployed on Choreo.

      As a web application developer, there may be instances where it becomes necessary to run the application on your personal workstation. In such situations, the expectation is for authentication and authorization during local development to work in the same manner as it would when the application is deployed to Choreo, eliminating the need to modify the source code.

      Choreo's local development capability ensures a seamless local application development experience where the authentication and authorization process aligns with Choreo\u2019s deployment environment. This facilitates a smoother transition from development to deployment, improving workflow efficiency.

      "},{"location":"develop-components/develop-web-applications/develop-web-applications-locally-with-managed-authentication/#how-local-development-works-in-choreo","title":"How local development works in Choreo","text":"

      Local development uses a proxy that sits in front of the locally running web application. This proxy intercepts all incoming requests. The requests to /choreo-apis/* and /auth/* are then forwarded to Choreo, while all other requests are forwarded to the locally running web application. The proxy runs on HTTPS using a self-signed certificate, crucial for secure, HTTP-only cookie-based managed authentication. Upon running the proxy, you can access the web application using the proxy's URL and start developing the application locally. You will observe that the behavior of the web application, in terms of the managed authentication functionality, is similar to how it would be after deploying to Choreo.

      "},{"location":"develop-components/develop-web-applications/develop-web-applications-locally-with-managed-authentication/#configure-local-development","title":"Configure local development","text":""},{"location":"develop-components/develop-web-applications/develop-web-applications-locally-with-managed-authentication/#prerequisites","title":"Prerequisites","text":"
      • Create a single-page application (SPA) with managed authentication enabled. For details on how to set up managed authentication for your web application, see Secure Web Applications with Managed Authentication.

      • Promote and deploy the application to the environment where you want to enable local development.

        Note

        • The web application that you run locally will use the same managed authentication configuration as the environment where you are configuring local development.
        • Local development is only allowed in non-critical environments.
      "},{"location":"develop-components/develop-web-applications/develop-web-applications-locally-with-managed-authentication/#apply-configurations","title":"Apply configurations","text":"
      1. Sign in to the Choreo Console.
      2. In the Component Listing pane, click on the component you created and deployed by following the prerequisites.
      3. In the left navigation menu, click Deploy.
      4. Go to the respective environment card depending on the environment where you want to enable local development and click Local Development.
      5. In the Local Development pane that opens, click the Local Development toggle to enable it.
      6. If you want to update the port on which the local development proxy server runs, click to expand Advanced Configurations and specify a value for Proxy Port.
      7. Click Apply.

      Now you have done the necessary configurations to set up local development. The next section walks you through the steps to access your web application so that you can develop it locally.

      "},{"location":"develop-components/develop-web-applications/develop-web-applications-locally-with-managed-authentication/#access-your-web-application-to-develop-it-locally","title":"Access your web application to develop it locally","text":""},{"location":"develop-components/develop-web-applications/develop-web-applications-locally-with-managed-authentication/#prerequisites_1","title":"Prerequisites","text":"
      • Ensure that local development is enabled in the environment where you want to proceed with local development.
      • Ensure that your web application is running locally on http://localhost on a specific port.
      "},{"location":"develop-components/develop-web-applications/develop-web-applications-locally-with-managed-authentication/#access-your-web-application-locally","title":"Access your web application locally","text":"

      You can either use the Choreo built-in identity provider or external identity provider to access your web application locally.

      Use the Choreo built-in identity providerUse an external identity provider
      1. Sign in to the Choreo Console.
      2. In the Component Listing pane, click on the component you created and deployed by following the prerequisites.
      3. In the left navigation menu, click Deploy.
      4. Go to the respective environment card depending on the environment where you want to enable local development and click Local Development.
      5. In the Local Development pane that opens, copy the command given under Step 1.
      6. Paste the command in a terminal, ensure you replace [APP_PORT] with the port on which your application is running locally, and run the command.

      7. To access the application and proceed to develop it, go to the URL given under Step 2 in the Local Development pane.

        Note

        The local development proxy runs on HTTPS using a self-signed certificate. Your browser may warn that the certificate is not valid. Accept the risk and proceed.

      1. Sign in to the Choreo Console.
      2. In the Component Listing pane, click on the component you created and deployed by following the prerequisites.
      3. In the left navigation menu, click Deploy.
      4. Go to the respective environment card depending on the environment where you want to enable local development and click Local Development.
      5. In the Local Development pane that opens, copy the redirect URLs given under Step 1.
      6. Go to the settings in the OAuth application in your identity provider and specify the copied URLs as allowed redirect URLs.
      7. Go to the Local Development pane in the Choreo Console and copy the command given under Step 2.
      8. Paste the command in a terminal, ensure you replace [APP_PORT] with the port on which your application is running locally, and run the command.

      9. To access the application and proceed to develop it, go to the URL given under Step 3 in the Local Development pane.

        Note

        The local development proxy runs on HTTPS using a self-signed certificate. Your browser may warn that the certificate is not valid. Accept the risk and proceed.

      "},{"location":"develop-components/sharing-and-reusing/create-a-connection/","title":"Create a Connection","text":"

      Connections in Choreo allow you to integrate Choreo components, or to integrate Choreo components to external services or resources. Connections provide a simple and uniform way to integrate with services and resources.

      To consume a service deployed on Choreo within your service, you must create a connection to the service you want to consume.

      To create a connection, follow the steps given below:

      1. In the Choreo Console, go to the top navigation menu and set the visibility level as project or component as follows:

        • Project Connection: Select an organization and a project in that organization.
        • Component Connection: Select an organization, a project in that organization, and a component in the selected project.

      2. From the left navigation menu, click Dependencies and then Connections. This page will list the currently available connections.

      3. Click +Create. The Create Connection page opens with the marketplace view for you to browse the available services. You can search and apply filters to efficiently find a service.
      4. Click on the service you want to connect to.
      5. Enter a name and a description for the connection and click Next. This displays the ServiceURL for the development and production environments.
      6. Click Finish.

      For step-by-step instructions on how to use a connection in your service, see Use a Connection in Your Service.

      For step-by-step instructions on how to use a connection in your web application, see Use a Connection in Your Web Application.

      "},{"location":"develop-components/sharing-and-reusing/use-a-connection-in-your-service/","title":"Use a Connection in Your Service","text":"

      Choreo allows you to share and reuse your services, accelerating development and enhancing efficiency in building integrated applications through connections.

      For step-by-step on instruction on creating a connection, see Create a Connection.

      To learn more about Choreo Connections, see the documentation on Connections.

      "},{"location":"develop-components/sharing-and-reusing/use-a-connection-in-your-service/#consume-a-service-through-a-connection","title":"Consume a service through a connection","text":"

      You can consume a Choreo-deployed service within another service. Consuming connections from within Choreo services is seamless and straightforward. Follow the steps below to consume a Choreo service:

      "},{"location":"develop-components/sharing-and-reusing/use-a-connection-in-your-service/#step-1-add-connection-configurations","title":"Step 1: Add connection configurations","text":"

      To integrate another service into your application, follow the steps below:

      1. Copy and paste the snippet from the in-line developer guide into the component-config file under the spec section.

        The following is a sample snippet:

        outbound:\nserviceReferences:\n- name: <SERVICE_NAME>\nconnectionConfig: <CONNECTION_ID>\nenv:\n- from: ServiceURL\nto: <YOUR_ENV_VARIABLE_NAME_HERE>\n- from: ConsumerKey\nto: <YOUR_ENV_VARIABLE_NAME_HERE>\n- from: ConsumerSecret\nto: <YOUR_ENV_VARIABLE_NAME_HERE>\n- from: TokenURL\nto: <YOUR_ENV_VARIABLE_NAME_HERE>\n
        Field Description Name The name of the service you are connecting to. ConnectionConfig The unique connection identifier for the connection. env The environment variable mapping. from The key of the configuration entry. to The environment variable name to which Choreo will inject the value of the key.

      2. Replace <YOUR_ENV_VARIABLE_NAME_HERE> with an appropriate environment variable name of your choice. If you have previously added an outbound service reference, append this as another item under serviceReferences.

        Upon deploying the component, Choreo automatically creates a subscription if applicable and populates the specified environment variables with actual values.

        The following table provides details on the configuration keys associated with the connection:

        Name Type Description Optional Sensitive ServiceURL string Service URL of the Choreo service false false ConsumerKey string Consumer key of the Choreo service false false ConsumerSecret string Consumer secret of the Choreo service false true TokenURL string Token URL of the STS false false
      "},{"location":"develop-components/sharing-and-reusing/use-a-connection-in-your-service/#step-2-read-configurations-within-the-application","title":"Step 2: Read configurations within the application","text":"

      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.

      The following is a sample code snippet in NodeJS:

      const serviceURL = process.env.SVC_URL;\n
      "},{"location":"develop-components/sharing-and-reusing/use-a-connection-in-your-service/#step-3-acquire-an-oauth-20-access-token","title":"Step 3: Acquire an OAuth 2.0 access token","text":"

      To consume a Choreo service with the visibility level set to organization or public and secured by the OAuth 2.0 security scheme, you must obtain an OAuth 2.0 token from the token endpoint. Subsequently, you can use the token to invoke the service.

      • For languages with OAuth 2.0-aware HTTP clients, you must pass the OAuth 2.0-related configurations such as client id, client secret and so on, obtained when creating the connection to your HTTP client configuration. The HTTP client autonomously manages token retrieval and refreshing.

      • For languages without OAuth 2.0-aware HTTP clients, you must manually initiate a call to the token endpoint. This includes fetching the token and managing token expiration and refresh directly within your application code. The following is a sample curl command to obtain a token:

        CONSUMER_KEY=\"your_consumer_key\"\nCONSUMER_SECRET=\"your_consumer_secret\"\nTOKEN_URL=\"your_token_url\"\n# Encode client credentials as Base64\nCLIENT_CREDENTIALS=$(echo -n \"$CLIENT_ID:$CLIENT_SECRET\" | base64)\ncurl -X POST $TOKEN_URL \\\n-H \"Content-Type: application/x-www-form-urlencoded\" \\\n-H \"Authorization: Basic $CLIENT_CREDENTIALS\" \\\n--data-urlencode \"grant_type=client_credentials\"\n
      "},{"location":"develop-components/sharing-and-reusing/use-a-connection-in-your-service/#step-4-invoke-the-service","title":"Step 4: Invoke the Service","text":"

      You can invoke the service as follows:

      • For languages with OAuth 2.0-aware HTTP clients, you can invoke the service in a straightforward manner. The HTTP client seamlessly manages OAuth 2.0 authentication without requiring additional intervention.

        As the service URL you can use the URL that you resolved in step 2. For sample requests and responses, see the API definition provided via the Choreo marketplace for the service.

      • For languages without OAuth 2.0-aware HTTP clients, you can use the token obtained in step 3 to make calls to the dependent service. Subsequently, add the obtained token to the HTTP authorization header with the bearer prefix. As the service URL you can use the URL that you resolved in step 2. For sample requests and responses, see the API definition of the service provided via the Choreo marketplace.

        The following is a sample code snippet in NodeJS:

        const response = await axios.get(serviceURL/{RESOURCE_PATH}, {\nheaders: {\n'Authorization': `Bearer ${accessToken}`\n}\n});\n

        Note

        If you want to consume a Choreo service at the project visibility level, you don't need to obtain a token. You can directly invoke the service using the resolved URL.

      "},{"location":"develop-components/sharing-and-reusing/use-a-connection-in-your-web-application/","title":"Use a Connection in Your Web Application","text":"

      Choreo simplifies the process of integrating services into your web application. The approach to connect to a service can vary based on your web application.

      To connect to a selected service, follow the step-by-step instructions given below depending on the authentication mechanism used in your web application.

      Managed authenticationCustom authentication or no authentication

      Choreo-managed authentication allows you to seamlessly handle authentication for your web application. You can configure your web application to work with the built-in identity provider of Choreo or any external identity provider that supports OIDC/OAuth2.0

      Note

      Choreo's managed authentication is currently available only for web applications created with React, Angular, or Vue.js buildpacks.

      Follow the steps below to use an existing connection within your web application:

      Step 1: Add the connection configuration

      To integrate a service into your application, you must first add the connection configuration as follows:

      1. For single page applications (SPAs), you must add the connection configuration as a file mount. You can mount a file via the Configurations pane on the Deploy page. You must mount a file (for example, config.js) and add the configuration provided in the in-line developer documentation into it.

        The following is a sample configuration:

             window.configs = {\napiUrl: '<SERVICE_URL>',        };\n

      2. To ensure accessibility of the config.js file via JavaScript at runtime, add a script tag as follows in the index.html file to reference the config.js file:

        <!DOCTYPE html>\n<html lang=\"en\">\n<head>\n<meta charset=\"utf-8\" />\n<title>My React App</title>\n</head>\n<body>\n<div id=\"root\"></div>\n<script src=\"%PUBLIC_URL%/config.js\"></script>\n</body>\n</html>\n

        Note

        If you use an external IdP, you must add the IdP's configuration to the same file.

        For more information on working with IdPs, see Configure Asgardeo as an External Identity Provider.

      Step 2: Read the configuration

      Once you add the connection configuration, you can proceed to read the configuration from your application. The steps to read depend on the programming language you use.

      The following is a sample code snippet in NodeJS:

           const serviceURL = window?.configs?.apiUrl ? window.configs.apiUrl : \"/\";\n

      Step 3: Invoke the service

      If you use Choreo-managed authentication, Choreo handles the security handshaking for the application during deployment. The connected service will be accessible under the same domain as your application. Therefore, you can call the configured path directly using your preferred HTTP client.

      The following is a sample code snippet in NodeJS:

           const response = await axios.get(serviceURL/{RESOURCE_PATH});\n

      Note

      If you are using an external IdP provider instead of Choreo-managed authentication, you must obtain an access token from your IdP and add it to the HTTP authorization header with the bearer prefix.

      If you are not using Choreo-managed authentication or your web application lacks authentication, follow the steps below to connect to a service from your web application:

      Step 1: Add the connection configuration

      For single-page applications (SPAs), you must add the connection configuration as a file mount. You can mount a file via the Configurations pane on the Deploy page. You must mount a file (for example, config.js) and add the following configuration into it.

      The following is a sample configuration:

           window.configs = {\napiUrl: '<SERVICE_URL>',\nconsumerKey: '<CONSUMER_KEY>',\nconsumerSecret: '<CONSUMER_SECRET>',\ntokenUrl: '<TOKEN_URL>',\n};\n

      For other types of web applications, you must add the respective configuration into your application.

      Step 2: Read the configuration

      Once you have added the connection configuration, you can proceed to read the configuration from your application. The steps to read depend on the programming language you use.

      The following is a sample code snippet in NodeJS:

           const serviceURL = window?.configs?.apiUrl ? window.configs.apiUrl : \"/\";\n

      Step 3: Acquire an OAuth 2.0 access token

      • For languages with OAuth 2.0-aware HTTP clients, you must pass the OAuth 2.0-related configurations such as client id, client secret and so on, obtained when creating the connection to your HTTP client configuration. The HTTP client autonomously manages token retrieval and refreshing.

      • For languages without OAuth 2.0-aware HTTP clients, you must manually initiate a call to the token endpoint. This includes fetching the token and managing token expiration and refresh directly within your application code. The following is a sample curl command to obtain a token:

        CONSUMER_KEY=\"your_consumer_key\"\nCONSUMER_SECRET=\"your_consumer_secret\"\nTOKEN_URL=\"your_token_url\"\n# Encode client credentials as Base64\nCLIENT_CREDENTIALS=$(echo -n \"$CLIENT_ID:$CLIENT_SECRET\" | base64)\ncurl -X POST $TOKEN_URL \\\n-H \"Content-Type: application/x-www-form-urlencoded\" \\\n-H \"Authorization: Basic $CLIENT_CREDENTIALS\" \\\n--data-urlencode \"grant_type=client_credentials\"\n

      Step 4: Invoke the service

      You can invoke the service as follows:

      • For languages with OAuth 2.0-aware HTTP clients, you can invoke the service in a straightforward manner. The HTTP client seamlessly manages OAuth 2.0 authentication without requiring additional intervention.

        As the service URL you can use the URL that you resolved in step 2 above. For sample requests and responses, see the API definition provided via the Choreo marketplace for the service.

      • For languages without OAuth 2.0-aware HTTP clients, you can use the token obtained in step 3 above to make calls to the dependent service. Subsequently, add the obtained token to the HTTP authorization header with the bearer prefix.

        As the service URL you can use the URL that you resolved in step 2 above. For sample requests and responses, see the API definition of the service provided via the Choreo marketplace.

        The following is a sample code snippet in NodeJS:

            const response = await axios.get(serviceURL/{RESOURCE_PATH}, {\nheaders: {\n'Authorization': `Bearer ${accessToken}`\n}\n})\n
      "},{"location":"devops-and-ci-cd/autoscale-component-replicas/","title":"Autoscale Component Replicas","text":"

      Choreo allows you to automatically scale your component replicas up or down in number based on resource consumption to ensure high availability.

      Note

      Autoscaling capabilities are only available in paid plans for private data plane organizations. In the free tier, components run in a single-replica, low-availability mode.

      The following parameters allow you to scale component replicas:

      • Min replicas: The minimum number of replicas to run at any given time. It is recommended to keep the value at a minimum of 2.
      • Max replicas: The maximum number of replicas to scale up to. In the cloud data plane, this is restricted to a maximum of 5. There is no restriction on the value in private data planes.
      • CPU Threshold: The average CPU utilization across all running replicas. If the CPU utilization across all active instances reaches the threshold, the number of active replicas automatically scales up until the average CPU utilization falls below the threshold.
      • Memory Threshold: The average memory usage across all running replicas. Like the CPU Threshold, if all active instances reach the memory threshold, the number of active replicas automatically scales up until the average memory usage falls below the threshold.

      Tip

      If you update a scaling parameter, it may not immediately reflect in the Choreo Console because the change can take some time to propagate.

      Run a fixed number of replicas

      If you want to run exactly 3 replicas for a component, you must set the minimum and maximum replicas to 3.

      Scale to zero

      • Although it is possible to set the minimum number of replicas to 0, your component does not scale to zero automatically during low usage. It can only go down to 1 replica.
      • Setting both the minimum and maximum replicas to 0 suspends the deployment.
      "},{"location":"devops-and-ci-cd/configure-container-resources-commands-and-arguments/","title":"Configure Container Resources, Commands, and Arguments","text":"

      In Choreo, you can view detailed information about the container that comprises a component, such as its image tag, the corresponding commit ID, any imposed resource usage limits, and so on.

      Each component in Choreo is limited to a single main container.

      Resource Limits

      Resource limits ensure that a single component does not take up more resources than it requires, which can affect other workloads on the data plane. If a process exceeds the allocated memory limit, the corresponding container will be forcefully shut down and restarted. If the process exceeds the allocated CPU limit, it gets throttled and can result in significant latencies in compute and I/O operations.

      Choreo allows you to edit the default container configuration depending on your requirement.

      "},{"location":"devops-and-ci-cd/configure-container-resources-commands-and-arguments/#update-container-configurations","title":"Update container configurations","text":"

      Follow these steps to update container configurations:

      1. Sign in to the Choreo Console.
      2. In the Component Listing pane, click on the component for which you want to edit container configurations.
      3. In the left navigation menu, click DevOps and then click Containers.
      4. On the Containers page, click Edit to update the corresponding container configuration.

      5. Apply the necessary changes and click Save.

      The following topics walk you through the container configuration changes you can apply.

      "},{"location":"devops-and-ci-cd/configure-container-resources-commands-and-arguments/#update-resource-requests-and-limits","title":"Update resource requests and limits","text":"

      Note

      The capability to update resource requests and limits is only available in paid pricing plans.

      To update resource requests and limits, move the corresponding slider to a required position. A resource request cannot be less than its corresponding limit.

      "},{"location":"devops-and-ci-cd/configure-container-resources-commands-and-arguments/#set-the-image-pull-policy","title":"Set the image pull policy","text":"

      You can select one of the following options as the image pull policy.

      • Always: The image is always pulled from the container registry, even if a matching tag is already present in the data plane.

      • If Not Present - The image is pulled from the container registry only if a matching image is not present in the data plane.

        Tip

        The recommended option is If Not Present.

      "},{"location":"devops-and-ci-cd/configure-container-resources-commands-and-arguments/#specify-container-ports","title":"Specify container ports","text":"

      You can specify appropriate values for the Container Port and Service Port. The Service Port is the port exposed outside of the container to your project-scoped endpoint. If you do not know the value to specify as the Service Port, specify the Container Port value in both fields.

      Tip

      You do not need to configure port values manually for Ballerina components. The capability to edit port values is primarily for containerized/Dockerfile-based components.

      You can also select an appropriate Protocol.

      "},{"location":"devops-and-ci-cd/configure-container-resources-commands-and-arguments/#define-a-command-and-arguments-for-the-container","title":"Define a command and arguments for the container","text":"

      You can define a command and arguments for a container when you want to provide or override the ENTRYPOINT of a container. For example, in a scenario where you want to run legacy or third-party applications, you would want to provide or override the ENTRYPOINT of a container.

      When you define a command and arguments,

      • It specifies the ENTRYPOINT array and it is not executed within a shell.
      • Variable references $(VAR_NAME) are expanded using the container's environment. If a variable cannot be resolved, the reference in the input string will be unchanged.
      • $$ are reduced to $, which allows escaping the $(VAR_NAME) syntax. This means that \"$$(VAR_NAME)\" produces the string literal \"$(VAR_NAME)\".
      • Escaped references are never expanded, regardless of whether the variable exists or not.

      The ENTRYPOINT of the container image is used if you do not define a command and arguments for the container.

      "},{"location":"devops-and-ci-cd/configure-storage/","title":"Configure Storage","text":"

      All components you create in Choreo have a default read-only file system, which you cannot access or write to from your applications.

      Volume mounts allow you to create either temporary or persisted writable file system storage locations for your applications.

      "},{"location":"devops-and-ci-cd/configure-storage/#volume-mount-types","title":"Volume mount types","text":"Type Description Empty Directory (In-Memory) A fast, temporary in-memory (tmpfs) storage location. This volume gets erased when you restart or remove the attached container. Available on all data planes. Empty Directory (Disk) A temporary storage location on disk. This volume gets destroyed when you restart or remove the attached container. Only available on private data planes. Persistent Volume A permanent storage location. This volume persists even if you restart or remove the attached container. Only available on private data planes.

      Tip

      All components have a writable location in the /tmp directory at the time of component creation. You can also configure other writable locations if required.

      "},{"location":"devops-and-ci-cd/configure-storage/#create-a-temporary-storage-space-for-your-container","title":"Create a temporary storage space for your container","text":"

      Empty directory (in-memory or on-disk) mounts allow you to create temporary file systems that your application can read from and write to. This option provides a convenient way to create a scratch space to write files temporarily before storing them in a more permanent storage location such as a cloud-backed storage bucket. For example, unzipping a file, temporarily writing results from a memory-intensive operation to disk, a temporary local cache, etc. However, it is important to note that these volumes destroy when you restart or update a container because the volumes are attached to the lifetime of a container.

      Follow these steps to create a temporary storage space for your container:

      1. Sign in to the Choreo Console.
      2. In the Component Listing pane, click on the component for which you want to create a temporary storage.
      3. In the left navigation menu, click DevOps and then click Storage.
      4. Click + Create.
      5. In the Create a Volume Mount pane, specify a name for the volume and select Empty Directory (In-Memory).

      1. Click Next.

        In-memory (tmpfs) storage uses up container memory

        Storage capacity for this type of volume will count against the container's memory limit. Uncontrolled writes to this location may starve your application process of memory and can result in the container getting killed and restarted if the memory limits exceed.

      2. To add a mount location, specify a Mount Path and click Add mount.

        Tip

        • You can add multiple mount locations to a volume.
        • Mount paths should be absolute file paths and will be available to your application to read/write from.

      3. Click Create. This applies the volume mount immediately to your container and triggers a rolling restart.

      "},{"location":"devops-and-ci-cd/configure-storage/#create-a-persistent-storage-space-for-your-container","title":"Create a persistent storage space for your container","text":"

      Follow these steps to create a persistent storage space for your container:

      Note

      Persistent volume options are only available in private data plane organizations.

      1. Sign in to the Choreo Console.
      2. In the Component Listing pane, click on the component for which you want to create a persistent storage.
      3. In the left navigation menu, click DevOps and then click Storage.
      4. Click + Create.
      5. In the Create a Volume Mount pane, specify a name for the volume and select Persistent Volume.
      6. Select a Storage Class.
      7. Move the Storage Capacity slider to set the required capacity.

      8. Select an appropriate Access Mode.

        Check and specify an access mode supported by the storage class

        • You must check the cloud provider documentation to select an appropriate access mode that the storage class supports. Choreo does not verify whether the storage class supports the access mode you select.
        • If the storage class does not support the access mode you select, it can result in a runtime mount error.

      9. Click Next.

      10. To add a mount location, specify a Mount Path and click Add mount.

        Tip

        • You can add multiple mount locations to a volume.
        • Mount paths should be absolute file paths and will be available to your application to read/write from.

      11. Click Create. This applies the volume immediately to your container.

      "},{"location":"devops-and-ci-cd/configure-vpns-on-the-choreo-cloud-data-plane/","title":"Configure VPNs on the Choreo Cloud Data Plane","text":"

      Secure access to private networks from the Choreo cloud data plane is an essential use case for cloud data plane users.

      Choreo allows this secure connection using Tailscale. For this, Choreo provides a prebuilt Tailscale image component that can act as a forward proxy, which you can deploy in your Choreo project as a service. This service allows you to forward traffic to your external networks via Tailscale\u2019s peer-to-peer WireGuard network.

      The following diagram illustrates the high-level deployment architecture of the Tailscale pre-installed forward proxy:

      Let's take a look at the specifics of each part to understand the deployment architecture.

      • Choreo project

        In Choreo, a project groups various components. For more information on what a project in Choreo is, see the documentation on Project.

      • Tailscale proxy

        This acts as the Tailscale pre-installed forward proxy, facilitating secure peer-to-peer WireGuard connections from the Choreo cloud data plane to private networks. It includes a Tailscale Daemon, SOCKS5 proxy, and a configurable TCP forwarder.

        • Tailscale daemon

          This is the core component of Tailscale. It is a software service that provides secure network connectivity and private networking solutions. For more details see the Tailscale documentation.

        • SOCKS5 proxy

          This uses Tailscale\u2019s userspace networking mode, rather than the kernel mode. Therefore, the inbuilt SOCKS5 proxy handles the forwarded traffic and directs it through the Tailscale network.

        • TCP forwarder

          Forwards inbound TCP (transmission control protocol) traffic from the Tailscale proxy container\u2019s network interface to the SOCKS5 proxy, ensuring it reaches its destination via the secured WireGuard tunnel.

      • User applications and the Choreo API gateway

        User applications within the same namespace (project) can use the Kubernetes service created to front the Tailscale proxy, for connecting to the corresponding private endpoints. You can either expose this service within the organization via the internal API gateway or expose it to the public via the external API gateway. For more details, see the documentation on Choreo endpoints.

      Now that you understand the deployment architecture, let\u2019s explore how you can use Tailscale to secure connections to your private networks.

      "},{"location":"devops-and-ci-cd/configure-vpns-on-the-choreo-cloud-data-plane/#configure-and-use-tailscale-to-access-private-network-endpoints","title":"Configure and use Tailscale to access private network endpoints","text":"

      This section walks you through the steps to create, configure, deploy, and use the Tailscale proxy component.

      Let's get started.

      "},{"location":"devops-and-ci-cd/configure-vpns-on-the-choreo-cloud-data-plane/#prerequisites","title":"Prerequisites","text":"
      • Understand the basics of how Tailscale works.
      • Have a Tailscale account (Tailnet). There are multiple plans available for you to set up your Tailscale network. For details, see Tailscale plans.
      • Install Tailscale and connect your private data center or server to it, so that your private services are accessible via your Tailscale network. To quickly get started with Tailscale, see the Tailscale quickstart.

      • If you are signing in to the Choreo Console for the first time, create an organization as follows:

        1. Go to https://console.choreo.dev/, and sign in using your Google, GitHub, or Microsoft account.
        2. Enter a unique organization name. For example, Stark Industries.
        3. Read and accept the privacy policy and terms of use.
        4. Click Create.

        This creates the organization and opens the organization home page.

      "},{"location":"devops-and-ci-cd/configure-vpns-on-the-choreo-cloud-data-plane/#step-1-create-the-tailscale-proxy","title":"Step 1: Create the Tailscale proxy","text":"Step 1.1: Create a project

      Follow the steps given below to create a project:

      1. Go to https://console.choreo.dev/ and sign in. This opens the organization home page.
      2. On the organization home page, click + Create Project.

      3. Enter a display name, unique name, and description for the project. You can enter the values given below:

        Info

        In the Name field, you must specify a name to uniquely identify your project in various contexts. The value is editable only at the time you create the project. You cannot change the name after you create the project.

        Field Value Project Display Name Tailscale Proxy Project Name tailscale-proxy-project Project Description My Tailscale project

      4. Click Create. This creates the project and takes you to the project home page.

      Step 1.2: Create the Tailscale proxy component
      1. On the project home page, click Service under Create a Component.

      2. Enter a display name, component name, and a description for the service. For this guide, let's enter the following values:

        Field Value Component Display Name Tailscale proxy Component Name tailscale-proxy Description Tailscale proxy component

      3. Click the Container Registry tab.

      4. In the Container Registry list, select Choreo Samples Registry.
      5. Click the Tailscale Proxy card.
      6. Click Create.

      Now you have successfully created the Tailscale proxy. You can proceed to configure and deploy it.

      "},{"location":"devops-and-ci-cd/configure-vpns-on-the-choreo-cloud-data-plane/#step-2-configure-and-deploy-the-tailscale-proxy","title":"Step 2: Configure and deploy the Tailscale proxy","text":"

      Here, you will add the required volume mounts, set the Tailscale authentication key, configure the TCP forwarder, configure endpoints, and deploy the Tailscale proxy. Follow the steps given below:

      Step 2.1: Add required volume mounts

      Tailscale requires the following volume mounts for its operations:

      • /var/run/tailscale
      • /.local

      To create the volume mounts, follow the step-by-step instructions in Configure Storage.

      Step 2.2: Configure and deploy the component

      To configure and deploy the component, follow the steps given below:

      1. In the left navigation menu, click Deploy.
      2. On the Build Area card, click Configure & Deploy.
      3. In the Environment Configurations pane that opens, click + Add and add the TS_AUTH_KEY environment variable as a secret. To add the environment variable, you must obtain an authentication key from your Tailscale network.
        • For details on how to obtain an authentication key from your Tailscale network, see Auth keys in the Tailscale documentation.
      4. Click Next.
      5. In the File Mount pane that opens, click + Add.

      6. To mount a configuration file to the Tailscale proxy component and specify the port mapping for the TCP forward proxy running there, do the following:

        1. Specify /config.yaml as the Mount Path.

        2. Specify the following in the sample configuration file: 

          portMappings:\n    8080: \"100.108.78.93:8090\"\n    8081: \"100.108.78.93:1433\"\n

          Note

          In this sample configuration, the TCP traffic arriving at port 8080 on your Tailscale proxy will be forwarded to port 8090 on the node with IP address 100.108.78.93 in your Tailscale network. Similarly, port 8081 will map to the corresponding address. You can find the IP addresses of your nodes on the Tailscale machines page in your Tailscale network's admin console or via the Tailscale clients running on your machine.

      7. Click Next.

      8. In the Endpoints pane that opens, click + Add and edit the endpoints.yaml configuration to expose your Tailscale proxy as a service. The following is a sample endpoints.yaml configuration you can use:

        Note

        The sample endpoints.yaml file given below defines two project-level endpoints. These endpoints can be used by other components within the same project to access the services. If you want to directly expose your private endpoint via the Choreo gateway either with the Public or Organization visibility, you can set the networkVisibility property of the endpoint to Public or Organization.

        version: 0.1\nendpoints:\n- name: Private HTTP service\nport: 8080\ntype: REST\nnetworkVisibility: Project\ncontext: /\n- name: Private DB service\nport: 8081\ntype: TCP\nnetworkVisibility: Project\ncontext: /\n

      9. Click Save.

      10. Click Next and then click Deploy.

        Note

        Deploying the component may take a while. You can track the progress by observing the logs. Once the deployment is complete, the build status changes to Active on the Development environment card.

      When the component is deployed, you can observe a new node connected to your Tailscale network. To view this, go to the Tailscale machines page of your Tailscale coordination server.

      "},{"location":"devops-and-ci-cd/configure-vpns-on-the-choreo-cloud-data-plane/#step-3-access-private-network-endpoints-with-the-tailscale-proxy","title":"Step 3: Access private network endpoints with the Tailscale proxy","text":"

      Now you have successfully deployed the Tailscale proxy in your project and it is connected to your Tailnet. You can proceed to use the Tailscale proxy to provision access for other components to securely access private network endpoints.

      You can configure endpoints of the Tailscale proxy to use it for various aspects within Choreo.

      "},{"location":"devops-and-ci-cd/configure-vpns-on-the-choreo-cloud-data-plane/#post-deployment-actions","title":"Post-deployment actions","text":""},{"location":"devops-and-ci-cd/configure-vpns-on-the-choreo-cloud-data-plane/#handle-node-key-expiry","title":"Handle node key expiry","text":"

      Tailscale nodes have a default node key expiry time of 180 days. Nodes require re-authentication after key expiry to avoid connection losses and application downtime. There is an option to disable node key expiry if necessary. For more details, see Node key expiry documentation.

      "},{"location":"devops-and-ci-cd/configure-vpns-on-the-choreo-cloud-data-plane/#handle-auth-key-expiry","title":"Handle auth key expiry","text":"

      Auth keys are used to register new nodes into your Tailscale network. The default expiry time for auth keys is 90 days, but nodes remain connected even after auth key expiry. This becomes an issue only if the Tailscale Proxy component is redeployed or restarted.

      "},{"location":"devops-and-ci-cd/configure-vpns-on-the-choreo-cloud-data-plane/#update-port-mapping-configurations","title":"Update port mapping configurations","text":"

      If you want to add a new private endpoint to your network and access it via the same Tailscale proxy within Choreo, you must add a new port mapping entry in the port mapping configuration of your Tailscale proxy deployment.

      "},{"location":"devops-and-ci-cd/configure-vpns-on-the-choreo-cloud-data-plane/#best-practices","title":"Best practices","text":""},{"location":"devops-and-ci-cd/configure-vpns-on-the-choreo-cloud-data-plane/#configure-health-checks","title":"Configure health checks","text":"

      Since the Tailscale proxy acts as a forward proxy, it is important to configure health checks. You can use one of the open ports of the TCP forwarder as a health endpoint. For details on how to set up health probes in Choreo, see Set up health checks.

      "},{"location":"devops-and-ci-cd/configure-vpns-on-the-choreo-cloud-data-plane/#use-tailscale-acls","title":"Use Tailscale ACLs","text":"

      You can use Tailscale ACLs to precisely manage permission for users and devices on your Tailnet.

      "},{"location":"devops-and-ci-cd/configure-vpns-on-the-choreo-cloud-data-plane/#disable-scale-to-zero-for-the-tailscale-proxy","title":"Disable scale-to-zero for the Tailscale proxy","text":"

      It is recommended to disable Scale-to-Zero for the Tailscale proxy because it acts as a forward proxy and should always be up and running to make consistent connections with the Tailscale VPN mesh. If you enable Scale-to-Zero, you may experience service downtime.

      "},{"location":"devops-and-ci-cd/configure-vpns-on-the-choreo-cloud-data-plane/#run-multiple-replicas-with-hpa-horizontal-pod-autoscaler","title":"Run multiple replicas with HPA (horizontal pod autoscaler)","text":"

      To achieve high availability and resiliency for the Tailscale proxy, you must run multiple replicas with HPA. To configure multiple replicas for the Tailscale proxy component, go to the Scaling page under DevOps. For more details, see Autoscale component replicas

      "},{"location":"devops-and-ci-cd/configure-vpns-on-the-choreo-cloud-data-plane/#security-best-practices","title":"Security best practices","text":"

      Before deploying the Tailscale proxy in production environments, it is recommended to follow the Tailscale production best practices and security best practices.

      Note

      Choreo blocks incoming connections from other nodes in your Tailnet to the Tailscale proxy to prevent access to your project\u2019s namespace in the Choreo cloud data plane.

      "},{"location":"devops-and-ci-cd/configure-vpns-on-the-choreo-cloud-data-plane/#troubleshoot-issues","title":"Troubleshoot issues","text":"

      For assistance in resolving common Tailscale proxy issues, see Troubleshoot Tailscale proxy issues.

      "},{"location":"devops-and-ci-cd/manage-configurations-and-secrets/","title":"Manage Configurations and Secrets","text":"

      Choreo allows you to easily manage and version your component's configurations and secrets as file mounts or environment variables.

      Note

      All configurations and secrets applied to a Choreo component are stored in an encrypted secret vault in the cloud data plane, which is managed by WSO2. If you are on a private data plane, the configurations and secrets are stored in an Azure key vault or AWS secret manager attached to your data plane in your cloud environment.

      "},{"location":"devops-and-ci-cd/manage-configurations-and-secrets/#the-difference-between-configurations-and-secrets","title":"The difference between configurations and secrets","text":"

      Choreo considers all configurations and secrets to be sensitive content when storing them, but gives you the option to choose between secret or configuration when you create a file mount or an environment variable.

      • Secrets are write-only. Once you create a secret, you cannot see or retrieve its content via the Choreo Console. However, you can overwrite the existing content at any time.

      • Configurations can be read and updated via the Choreo Console after you create them.

        Note

        If you want to include sensitive data such as database passwords, cloud credentials, service accounts, and so on, the recommended approach is to use a secret instead of a configuration.

      "},{"location":"devops-and-ci-cd/manage-configurations-and-secrets/#apply-a-file-mount-to-your-container","title":"Apply a file mount to your container","text":"

      Follow these steps to apply a file mount to a component you have created:

      1. Sign in to the Choreo Console.
      2. In the Component Listing pane, click on the component for which you want to define configurations and secrets.
      3. In the left navigation menu, click DevOps and then click Configs & Secrets.
      4. Click + Create.
      5. In the Create a Config or Secret pane, click File Mount.

      6. If you want to create the file mount as a secret, select Mark as a Secret. Otherwise, proceed to the next step.

        Note

        If you create the file mount as a secret, you will not be able to read the file content after you create the file mount.

      7. In the Display Name field, specify a name for the file mount.

        Tip

        The display name does not affect the file mount or its content. It is only a reference to identify the configuration or secret you create.

      8. In the File Mount Path field, specify where to mount the file inside the container. Use an absolute file path with the file name and extension if applicable.

        Tip

        The file name in the mount path does not need to match the configuration name or the name of the file you upload.

      9. Upload a configuration file or copy and paste the configuration content into the editor.

      10. Click Create.

        Note

        Configurations and secrets are applied immediately to your environment on creation. To ensure that the container reflects the new content, your existing running replicas undergo a rolling restart.

      "},{"location":"devops-and-ci-cd/manage-configurations-and-secrets/#apply-environment-variables-to-your-container","title":"Apply environment variables to your container","text":"

      Follow these steps to apply environment variables to a component you have created:

      1. Sign in to the Choreo Console.
      2. In the Component Listing pane, click on the component for which you want to define configurations and secrets.
      3. In the left navigation menu, click DevOps and then click Configs & Secrets.
      4. Click + Create.
      5. In the Create a Config or Secret pane, click Environment Variables.

      6. If you want to create the environment variable values as secrets, select Mark as a Secret. Otherwise, proceed to the next step.

        Note

        If you create environment variables as secrets, you will not be able to read the values you set for the environment variables after you create them.

      7. In the Display Name field, specify a name to identify the configuration or secret.

        Tip

        The display name you specify does not affect the environment variables you set. It is only a reference to identify the configuration or secret you create.

      8. Under Add Environment Variables, specify the necessary environment variables as key-value pairs. You can click Add Item to add any number of environment variables.

      9. Click Create.

      "},{"location":"devops-and-ci-cd/manage-configurations-and-secrets/#update-an-existing-configuration-or-secret","title":"Update an existing configuration or secret","text":"

      Follow these steps to update a configuration or secret you have defined:

      1. Sign in to the Choreo Console.
      2. In the Component Listing pane, click on the component for which you want to update configurations and secrets.
      3. In the left navigation menu, click DevOps and then click Configs & Secrets.
      4. Click the edit icon corresponding to the configuration or secret you want to update.
      5. Apply the necessary changes and click Save.
      "},{"location":"devops-and-ci-cd/manage-configurations-and-secrets/#delete-an-existing-configuration-or-secret","title":"Delete an existing configuration or secret","text":"

      Follow these steps to delete a configuration or secret you have defined:

      1. Sign in to the Choreo Console.
      2. In the Component Listing pane, click on the component for which you want to delete configurations and secrets.
      3. In the left navigation menu, click DevOps and then click Configs & Secrets.
      4. Click the delete icon corresponding to the configuration or secret you want to delete.
      5. Enter the name of the configuration or secret to confirm deletion.
      6. Click Delete.
      "},{"location":"devops-and-ci-cd/manage-configurations-and-secrets/#manage-ballerina-configurables","title":"Manage Ballerina configurables","text":"

      Choreo manages the Ballerina configurables for the Ballerina components you create.

      When you deploy or promote a Ballerina application, you can modify the Ballerina configurables via the Deploy page.

      Tip

      You can use configurables instead of environment variables to add file mounts to a Ballerina component. Environment variables are primarily for components written in other languages.

      "},{"location":"devops-and-ci-cd/manage-environments/","title":"Manage Environments","text":"

      By default, all projects created in the cloud data planes (irrespective of the data plane region) are provisioned with two environments (i.e., development and production).

      The environments are listed in the order of deployment and promotion. The initial deployment takes place in the first environment and you can proceed to promote a component to subsequent environments.

      "},{"location":"devops-and-ci-cd/manage-environments/#create-a-new-environment","title":"Create a new environment","text":""},{"location":"devops-and-ci-cd/manage-environments/#prerequisites","title":"Prerequisites","text":"
      • To create additional environments, you must have a Choreo subscription or a private data plane.
      • To create a new environment in a private data plane organization, you must have the ENVIRONMENT-MANAGEMENT permission. By default, ENVIRONMENT-MANAGEMENT permission is granted to Admin and Choreo DevOps roles.

      To create a new environment, follow the steps given below:

      1. Sign in to the Choreo Console and switch to the organization where you want to create a new project.
      2. In the left navigation menu, click DevOps and then click Environments (note that this is the Environments page under your organization, not your projects).

      3. On the Environments page, click Create and specify the following details to create a new environment:

        • Name: A display name for the new environment.

        • Data Plane - The data plane to create the new environment.

          Tip

          The Data Plane list displays all the private data planes registered under your organization.

        • DNS Prefix: A DNS prefix to identify the exposed APIs in the environment. Here, the base domain depends on the custom domain attached to the API gateways provisioned on the selected data plane.

        • Mark environment as a Production environment: Select if you want this environment to be a production environment.

          Tip

          In Choreo, you can have multiple non-production and production environments. To work in a production environment, you must have privileged permissions to access and deploy to production environments.

      "},{"location":"devops-and-ci-cd/manage-environments/#change-the-order-of-promotion","title":"Change the order of promotion","text":"

      The order in which environments are listed on the Environments page is the same order in which promotion takes place.

      To change the order of promotion across environments in an organization, follow the steps given below:

      1. Sign in to the Choreo Console and switch to the organization for which you want to change the order of promotion.
      2. In the left navigation menu, click DevOps and then click Environments.

      3. On the Environments page, click and drag environment list items to rearrange the order of listed environments.

        Note

        Although changes to the order of promotion for environments are applied immediately, the change does not affect the components already running in environments. Only subsequent builds and promotions will follow the new order.

      To see the changes, go to the Deploy page of a component (in any project).

      "},{"location":"devops-and-ci-cd/manage-environments/#delete-an-environment","title":"Delete an environment","text":"

      To delete an environment, follow the steps given below:

      Warning

      Environment deletion is a permanent, non-reversible operation.

      1. Sign in to the Choreo Console and switch to your organization.
      2. In the left navigation menu, click DevOps and then click Environments.
      3. In the Environments list, click the delete icon corresponding to the environment you want to delete. This displays a confirmation dialog with details on the impact of deletion.
      4. Review the details, then type the environment name to confirm the deletion.
      5. Click Delete.
      "},{"location":"devops-and-ci-cd/set-up-health-checks/","title":"Set Up Health Checks","text":"

      Health checks ensure that a running container is always healthy and ready to serve traffic.

      "},{"location":"devops-and-ci-cd/set-up-health-checks/#liveness-probes","title":"Liveness probes","text":"

      Liveness probes run periodically on your container and restart if the probe fails. This allows the container to self-heal in scenarios where the application may have crashed or become unresponsive.

      "},{"location":"devops-and-ci-cd/set-up-health-checks/#readiness-probes","title":"Readiness probes","text":"

      Similar to liveness probes, readiness probes run periodically throughout the lifecycle of a container. However, unlike liveness probes, these probes do not restart the container if the probe fails. Instead, they stop the container from receiving network traffic.

      Readiness probes on single replicas

      You must be mindful when you configure readiness probes on a single-running replica. If the readiness probe fails, your application stops receiving traffic because there is only one active replica. The application may not recover unless the liveness probe fails and restarts the container.

      "},{"location":"devops-and-ci-cd/set-up-health-checks/#probe-types","title":"Probe types","text":"

      You can configure the following probe types for both readiness and liveness probes.

      "},{"location":"devops-and-ci-cd/set-up-health-checks/#http-get-request","title":"HTTP GET request","text":"

      This probe sends an HTTP GET request to a specified port and path on the container. A response status code in the range of 200-399 indicates that the request is a success.

      Depending on your requirement, you can configure additional HTTP headers.

      The recommended approach is to create a /healthz or /health endpoint in your service for this purpose.

      "},{"location":"devops-and-ci-cd/set-up-health-checks/#tcp-connection-probe","title":"TCP connection probe","text":"

      This probe attempts to open a socket to the container on the specified port. If it cannot establish a TCP connection, it becomes a failure.

      "},{"location":"devops-and-ci-cd/set-up-health-checks/#execute-a-command","title":"Execute a command","text":"

      This probe executes a given script inside the container. A non-zero return from the command is considered a failure.

      For example, [\"cat\", \"/tmp/healthy\"] is considered healthy if the file /tmp/healthy is present. If not, it becomes a failure (non-zero exit code). In such scenarios, the application is responsible for writing and maintaining this file in the specified location.

      "},{"location":"devops-and-ci-cd/set-up-health-checks/#configure-liveness-and-readiness-probes","title":"Configure liveness and readiness probes","text":"

      Follow these steps to configure liveness and readiness probes on a container:

      1. Sign in to the Choreo Console.
      2. In the Component Listing pane, click on the component for which you want to configure liveness and readiness probes.
      3. In the left navigation menu, click DevOps and then click Health Checks.
      4. On the Health Checks page, click + Create.

      5. Configure the liveness probe depending on your requirement.

      6. Click Save.

      7. Configure the readiness probe depending on your requirement.

      8. Click Save.

        Note

        You can update or remove a probe at any time.

      Follow these steps to ensure that the container works as expected:

      1. In the left navigation menu, click Runtime under DevOps.
      2. On the Runtime page, check the details to confirm that the container works as expected. If the container does not start, check the events and conditions to see if any of the probes are causing the container to fail.
      "},{"location":"devops-and-ci-cd/view-runtime-details/","title":"View Runtime Details","text":"

      In Choreo, you can view details about running replicas of a component in a specific environment (i.e., Development or Production).

      To view the runtime details of a component, follow the steps given below:

      1. Sign in to the Choreo Console.
      2. In the Component Listing pane, click on the component for which you want to view runtime details.
      3. In the left navigation menu, click DevOps and then click Runtime. This opens the Runtime page populated with data retrieved from the underlying Choreo data plane.

      The runtime details you can see here are analogous to a zoomed-in view of a specific environment on the Deploy page.

      The following topics walk you through the specific details you can view and actions you can perform via the Runtime page.

      "},{"location":"devops-and-ci-cd/view-runtime-details/#redeploy-a-release","title":"Redeploy a release","text":"

      On the Runtime page, you can click Redeploy Release to immediately redeploy all resources, including configurations and secrets, to a specific environment. This triggers a rolling update to sync all the latest changes to the data plane.

      What is a release?

      A release in Choreo uniquely identifies an underlying deployment of a component to an environment for a given version. For example, if you deploy a component to two environments across two versions, the component will have four active releases.

      The capability to redeploy a release also allows you to quickly restart all the running replicas of a component in a specific environment.

      "},{"location":"devops-and-ci-cd/view-runtime-details/#view-running-instances","title":"View running instances","text":"

      The running instances you see on the Runtime page provide insights into the active replicas of your component in the selected environment.

      • You can view details of each active replica and its associated real-time CPU and memory usage, status, restarts, and the time of the last activity.

      • If you want to see the real-time logs and information on conditions and events of a replica, click the menu icon of the replica and then click Real-time Logs or Conditions & Events depending on what you need to view. These options provide insights that help to diagnose issues in deployments.

        Note

        • All metrics such as the total and replica-level CPU and memory usage displayed on the Runtime page are real-time data and are instantaneous representations of a component's current state.
        • You can take a look at the observability metrics of a component to see historical data and usage trends.
      "},{"location":"devops-and-ci-cd/view-runtime-details/#observe-real-time-container-logs","title":"Observe real-time container logs","text":"

      Unlike the logs available in the Observability Metrics of a component, these logs are fetched in real-time from the data plane and are not historical. Therefore, you can only see logs of active containers and the last shutdown container.

      • Display Previous Logs: Enable to retrieve logs from the last shutdown/crashed/restarted container of an instance.
      • Since Seconds: Specify the duration in seconds to fetch corresponding logs.
      • Filter Logs: Enable to filter and displays matching log lines. This is a fuzzy string search.
      "},{"location":"devops-and-ci-cd/view-runtime-details/#view-container-conditions-and-events","title":"View container conditions and events","text":"

      Conditions and events provide information necessary to troubleshoot failing deployments.

      If a component is not behaving as expected and you cannot detect any issues via the application logs, these events can provide necessary debugging information, such as the following:

      • Failing health checks (liveness and readiness probes).
      • Missing or invalid configuration/secret mounts.
      • Missing or invalid storage volume mounts.
      • Scheduling issues in the underlying data plane.
      "},{"location":"devops-and-ci-cd/autoscale/autoscale-component-replicas/","title":"Autoscale Component Replicas","text":"

      Choreo allows you to automatically scale your component replicas up or down in number based on resource consumption to ensure high availability.

      Note

      Autoscaling capabilities are only available in paid plans for private data plane organizations. In the free tier, components run in a single-replica, low-availability mode.

      The following parameters allow you to scale component replicas:

      • Min replicas: The minimum number of replicas to run at any given time. It is recommended to keep the value at a minimum of 2.
      • Max replicas: The maximum number of replicas to scale up to. In the cloud data plane, this is restricted to a maximum of 5. There is no restriction on the value in private data planes.
      • CPU Threshold: The average CPU utilization across all running replicas. If the CPU utilization across all active instances reaches the threshold, the number of active replicas automatically scales up until the average CPU utilization falls below the threshold.
      • Memory Threshold: The average memory usage across all running replicas. Like the CPU Threshold, if all active instances reach the memory threshold, the number of active replicas automatically scales up until the average memory usage falls below the threshold.

      Tip

      If you update a scaling parameter, it may not immediately reflect in the Choreo Console because the change can take some time to propagate.

      Run a fixed number of replicas

      If you want to run exactly 3 replicas for a component, you must set the minimum and maximum replicas to 3.

      Scale to zero

      • Although it is possible to set the minimum number of replicas to 0, your component does not scale to zero automatically during low usage. It can only go down to 1 replica.
      • Setting both the minimum and maximum replicas to 0 suspends the deployment.
      "},{"location":"devops-and-ci-cd/autoscale/autoscale-components-with-scale-to-zero/","title":"Autoscale Components with Scale-to-Zero","text":"

      Choreo provides the scale-to-zero capability for HTTP applications you deploy in the data plane. This lets you run your components in a serverless mode.

      Scale to zero is very useful in lower environments, where you can significantly reduce infrastructure costs by scaling down idle workloads. In production environments, you can also use scale-to-zero capability if your application's behavior aligns with this feature behavior. In the paid tier, if you want to run your application with more guaranteed high availability, it is recommended to choose HPA (Horizontal Pod Autoscaler) scaling method and configure a minimum replica count of 2 or higher.

      "},{"location":"devops-and-ci-cd/autoscale/autoscale-components-with-scale-to-zero/#how-scale-to-zero-works-in-choreo","title":"How Scale to Zero works in Choreo","text":"

      Info

      For service components and web-apps you create after February 23, 2024, Choreo enables the scale-to-zero feature by default.

      When Scale to Zero is enabled, your apps will automatically scale down to zero unless they receive HTTP traffic. When the application receives an HTTP request, your workload quickly scales up from zero to handle the request. When a new request is received by the deployment, the deployment will scale up to one replica and serve the request. When the deployment remains idle for a set period (approximately 5 minutes), it will automatically scale back to zero until a new request is received.

      When Scale to Zero is enabled, you can set the maximum number of replicas for deployments with this capability. Choreo dynamically scales deployments up to meet high HTTP traffic demand, up to the specified number of replicas. If the pending requests surpass the defined threshold under Number of pending requests to spawn a new pod, Choreo automatically adds a new replica to handle the increased load.

      "},{"location":"devops-and-ci-cd/autoscale/autoscale-components-with-scale-to-zero/#enable-scale-to-zero","title":"Enable scale to zero","text":"

      For service components and web-apps you create after February 23, 2024, Choreo enables the scale-to-zero feature by default. When deploying or promoting the component, the deployment will automatically scale-to-zero. Upon the next request to the deployed service, a replica will be created to serve the request.

      Note

      • For the services which contain at least one endpoint with the network visibility as Project, Choreo will not automatically scale-to-zero those components when you deploy or promote them.
      • HTTP services that run on a port other than the below list of ports will not automatically scale-to-zero your component when deploying or promoting: 5000, 6000, 7000, 8000, 9000, 7070 to 7079, 8080 to 8089, and 9090 to 9099 or 8290.

      To enable scale-to-zero for service components created before February 23, 2024, follow the steps given below:

      1. Sign in to the Choreo Console.
      2. In the Component Listing pane, click on the component you want to scale-to-zero.
      3. Make sure the component is deployed to an environment and is ready to receive traffic.

      4. In the left navigation menu, click DevOps and then click Scaling.

        • If you are a free user, you will see a view similar to the one below. You can click the scale-to-zero card to enable scale-to-zero for your component.

        • If you are a paid user or you are running your applications in your own private data plane, you will see a view similar to the one below. You can click the scale-to-zero card to enable scale-to-zero for your component.

        Note

        The scale-to-zero service should start within 60 seconds. If it doesn\u2019t, the gateway will timeout the request.

      You can independently scale Choreo components in both the Development and Production environments. The deployment card indicates the scaling status of each environment. To configure the scale-to-zero feature for a specific environment, click on the scale-to-zero link, which redirects to the Devops \u2192 Scaling page.

      When you turn on the scale-to-zero for your application, the minimum replicas for your app will be set to zero. However, you can still select an appropriate maximum number of replicas.

      "},{"location":"devops-and-ci-cd/autoscale/autoscale-components-with-scale-to-zero/#limitations","title":"Limitations","text":"
      • The scale-to-zero feature currently exclusively supports web applications and HTTP services. TCP and HTTPS services are not supported to be scaled to zero.
      • To scale to zero, your HTTP service must run on one of the specified ports: 5000, 6000, 7000, 8000, 9000, 7070 to 7079, 8080 to 8089, and 9090 to 9099 or 8290. If you have an endpoint in your component running in any other port, your component will not automatically scale-to-zero when deploying or promoting. Also, if you try to switch to the \u201cscale-to-zero\u201d option in the \u201cDevops\u201d \u2192 \u201cScaling\u201d view, it will fail.

      • Scheduled tasks and manually triggered components cannot connect to a service on a project scope if scale-to-zero is enabled. Attempting to do so results in the following error:

        Host not found, not forwarding request.

        To allow a task-type component to invoke a project-level service, set it to HPA mode if you are on a paid plan, or to no scaling if you are on the Developer plan.

      "},{"location":"devops-and-ci-cd/autoscale/autoscale-components-with-scale-to-zero/#architecture","title":"Architecture","text":"

      When your Choreo application scales down to zero, an intermediary proxy service intercepts incoming requests. If a request is directed at your application, this service initiates a scale-up. Requests are held in the proxy's queue until your application becomes active. After scaling up, the proxy forwards the queued requests to your application.

      If your application remains without HTTP traffic for an extended period (default idle time is 5 minutes), it will be scaled down to zero until more HTTP requests arrive. Conversely, if there's a surge in HTTP traffic to your scaled-up application, Choreo will further increase its scale to manage the demand. Choreo considers adding additional replicas if the number of queued requests surpasses the 'Target Pending Requests' threshold, which is set to 100 by default. You can adjust this threshold in the user interface.

      Note

      The initial request after a long period of inactivity experiences a delay because the application must first scale up from zero. If your API operates in a service-chain sequence (e.g., service-1 activates service-2, which in turn calls service-3), this waiting time may extend further. If your application or its chain takes a considerable time to scale up, be aware that the first request might face a timeout.

      "},{"location":"devops-and-ci-cd/autoscale/autoscale-components-with-scale-to-zero/#troubleshooting","title":"Troubleshooting","text":"

      When Choreo enables scale-to-zero by default, it will configure the readiness probe with some default values. However, in some cases, you may observe that your first request responds with a 503 status code. To overcome these behaviors, fine-tune the readiness probe in the DevOps \u2192 Health Checks view to match your application's needs.

      "},{"location":"manage-databases-and-caches/billing-for-platform-services/","title":"Billing for Platform Services (Databases and Caches)","text":"

      Any platform services you create within your Choreo Organization will be included in your current Choreo subscription. The quantity included will vary depending on the service plan of the resources you create.

      A few important considerations:

      • Usage is billed hourly. If you create a database that you later remove within the same month, you will only be charged for the hours during which it was active.
      • Fixed pricing based on service plans. Choreo does not charge extra for network bandwidth usage.

      Try out the free trial

      Choreo provides a 7 day free trial for all database types on the 'Hobbyist' service plan (for free tier users).

      "},{"location":"manage-databases-and-caches/choreo-managed-caches/","title":"Choreo-Managed Cache","text":"

      Fully compatible with legacy Redis\u00ae OSS.

      Choreo-Managed Cache provides fully-managed in-memory NoSQL databases on AWS, Azure, GCP, and Digital Ocean and can be used as a cache, database, streaming engine, or message broker.

      "},{"location":"manage-databases-and-caches/choreo-managed-caches/#create-a-choreo-managed-cache","title":"Create a Choreo-Managed Cache","text":"

      Follow the steps below to create a Choreo-Managed Cache:

      1. Sign in to the Choreo Console at https://console.choreo.dev/.
      2. In the header, click the Organization list. This opens the organization home page.
      3. In the left navigation menu, click Dependencies and then click Databases.
      4. Click + Create and select Choreo-Managed Cache as the data store type. Provide a display name for this server and follow the instructions.
      5. Select a preferred cloud provider (AWS, Azure, GCP, or Digital Ocean).
        • The cloud provider provisions the compute and storage infrastructure for your data store.
        • The functionality remains the same across cloud providers, though service plans and costs may differ.
      6. Select a region for your data store.
        • Available regions depend on the selected cloud provider. Choreo currently supports US and EU regions across all providers.
      7. Select a service plan.
        • Service plans vary in terms of dedicated CPU, memory (RAM), and storage space allocated for your data store, as well as high-availability configurations for production use cases.
      8. Click Create.
      "},{"location":"manage-databases-and-caches/choreo-managed-caches/#connect-to-your-choreo-managed-cache","title":"Connect to your Choreo-Managed Cache","text":"

      To connect to your Choreo-Managed Cache, follow these guidelines:

      • Use any legacy Redis\u00ae OSS compatible driver (in any programming language) to connect to your Choreo-Managed Cache.
      • You can find the connection parameters in the Overview section in the Choreo Console under the relevant database. Note that Choreo-Managed Cache enforces TLS.
      • Choreo-Managed Cache instances accept traffic from the internet by default. You can restrict access to specific IP addresses and CIDR blocks under Advanced Settings.
      "},{"location":"manage-databases-and-caches/choreo-managed-caches/#high-availability-and-automatic-backups","title":"High availability and automatic backups","text":"

      The high availability and the automatic backup retention periods for a Choreo-Managed Cache can vary as follows depending on the service plan you select.

      Service plan High availability Backup features Backup history Hobbyist Single-node with limited availability. Single backup only for disaster recovery None Startup Single-node with limited availability. Single backup only for disaster recovery 1 day Business Two-node (primary + standby) with higher availability (automatic failover if the primary node fails). Automatic backups 3 days Premium Three-node (primary + standby + standby) with highest availability (automatic failover if the primary node fails). Automatic backups 13 days

      In general, service plans are recommended for production scenarios due to the following reasons:

      • Provides another physical copy of the data in case of hardware, software, or network failures.
      • Reduces the data loss window in disaster scenarios.
      • Ensures quicker restoration with controlled failover in case of failures, as the standby is already installed and running.
      "},{"location":"manage-databases-and-caches/choreo-managed-caches/#automatic-backups","title":"Automatic backups","text":"
      • Choreo runs full backups daily to automatically backup Choreo-Managed Caches and has write-ahead logs (WAL) copied at 5-minute intervals or for every new file generated.
      • Choreo encrypts all backups at rest.
      • Choreo automatically handles outages and software failures by replacing broken nodes with new ones that resume correctly from the point of failure. The impact of a failure will depend on the number of available standby nodes in the data store.
      "},{"location":"manage-databases-and-caches/choreo-managed-caches/#failure-recovery","title":"Failure recovery","text":"

      • Minor failures: Choreo automatically handles minor failures such as service process crashes or temporary loss of network access in all plans without requiring significant changes to the service deployment. Choreo automatically restores the service to normal operation once it automatically restarts the crashed process or when it restores the network access.

      • Severe failures: Failures such as losing a node entirely in case of hardware or severe software problems, require more drastic recovery measures. The monitoring infrastructure automatically detects a failing node when the node starts reporting issues in the self-diagnostics or when it stops communicating. In such cases, the monitoring infrastructure automatically schedules a new replacement node to be created.

        • In the event of a data store failover, the service URI of your service remains the same; only the IP address will change to point to the new primary node.
        • Hobbyist and Startup plans provide a single node, and in case of failure, a new node starts up, restores its state from the latest available backup, and resumes serving traffic.
        • As there is just a single/primary node, the caching service becomes unavailable for the duration of the restoration operation. Therefore, all write operations made since the last backup will be lost.
      "},{"location":"manage-databases-and-caches/choreo-managed-caches/#limitations","title":"Limitations","text":""},{"location":"manage-databases-and-caches/choreo-managed-caches/#connection-limits","title":"Connection limits","text":"

      The number of simultaneous connections in a Choreo-Managed Cache depends on the total available memory on the server instances.

      You can use the following to estimate:

      max_number_of_connections = 4 x m\n

      Here, m represents the memory in megabytes, where at least 10,000 connections are available, even on the smallest servers. For example, on a server with 4GB memory (4,096 MB), the simultaneous connections are:

      4 x 4096 = 16384 // 16k connections\n

      This number is estimated by the exact available memory so it can vary between different plans and cloud providers. To see the exact maximum connections allowed, use the * redis-cli and info command as follows:

      echo \"info\" | redis-cli -u REDIS_URI | grep maxclients\n
      "},{"location":"manage-databases-and-caches/choreo-managed-caches/#restricted-commands","title":"Restricted commands","text":"

      To maintain the stability and security of a managed environment, Choreo restricts certain commands on Choreo-Managed Cache services.

      Support for Lua scripts on Choreo-Managed Cache

      • Choreo-Managed Cache has built-in support for running Lua scripts to perform various actions directly on the server. Scripting is typically controlled using the EVAL, EVALSHA, and SCRIPT LOAD commands.
      • For all newly-created cache instances, EVAL, EVALSHA, and SCRIPT LOAD commands are enabled by default.

      The following commands are disabled on Choreo:

      • bgrewriteaof: Initiates a background append-only file rewrite.
      • cluster: Manages Caching cluster commands.
      • command: Provides details about all Caching commands.
      • debug: Contains sub-commands for debugging Caching.
      • failover: Manages manual failover of a master to a replica.
      • migrate: Atomically transfers a key from one caching instance to another.
      • role: Returns the role of the instance in the context of replication.
      • slaveof: Makes the server a replica of another instance, or promotes it as master.
      • acl: Manages caching access control lists.
      • bgsave: Creates a snapshot of the data set into a dump file.
      • config: Alters the configuration of a running caching server.
      • lastsave: Returns the UNIX timestamp of the last successful save to disk.
      • monitor: Streams back every command processed by the Caching server.
      • replicaof: Makes the server a replica of another instance.
      • save: Synchronously saves the dataset to disk.
      • shutdown: Synchronously saves the dataset to disk and then shuts down the server.

      The following eval commands are also disabled:

      • eval: Executes a Lua script server-side.
      • eval_ro: Read-only variant of the eval command.
      • evalsha: Executes a script cached on the server side by its SHA1 digest.
      • evalsha_ro: Read-only variant of the evalsha command.
      • fcall: Calls a Caching function.
      • fcall_ro: Read-only variant of the fcall command.
      • function: Manages Caching functions.
      • script: Manages the script cache.
      "},{"location":"manage-databases-and-caches/choreo-managed-databases-and-caches/","title":"Choreo-Managed Databases, Vector Databases, and Caches","text":"

      Choreo allows you to create PostgreSQL and MySQL databases as well as Choreo-Managed Cache instances on all major cloud providers (AWS, Azure, GCP, and DigitalOcean) as fully Choreo-managed platform services. These databases and caches can be seamlessly provisioned to offer persistence and caching capabilities for all your Choreo components. Choreo provides various service plans for each type, ranging from smaller instances for development purposes to production-grade databases with automatic backups and high-availability multi-nodes.

      "},{"location":"manage-databases-and-caches/choreo-managed-databases-and-caches/#postgresql-on-choreo","title":"PostgreSQL on Choreo","text":"

      PostgreSQL (also known as Postgres), is an open-source object-relational database management system. You can create PostgreSQL databases on Choreo as fully Choreo-managed, flexible SQL databases that are ideal for both structured and unstructured data. If you want to perform an efficient vector similarity search, you can create a PostgreSQL vector database.

      • Create a PostgreSQL database on Choreo
      "},{"location":"manage-databases-and-caches/choreo-managed-databases-and-caches/#mysql-on-choreo","title":"MySQL on Choreo","text":"

      MySQL is a user-friendly, flexible, open-source relational database management system with a well-established history in the SQL database realm. Choreo allows you to swiftly create fully Choreo-managed MySQL databases, enabling rapid setup and utilization.

      • Create a MySQL database on Choreo
      "},{"location":"manage-databases-and-caches/choreo-managed-databases-and-caches/#choreo-managed-cache","title":"Choreo-Managed Cache","text":"

      A fully-managed cache compatible with legacy Redis\u00ae OSS. A versatile, in-memory NoSQL database that serves as a cache, database, streaming engine, and message broker. Choreo-managed Cache allows you to have fully-managed instances that can be swiftly provisioned and integrated into your applications within minutes.

      • Create a Choreo-managed Cache

      PostgreSQL, MySQL, and Redis\u00ae are trademarks and property of their respective owners. All product and service names used in this documentation are for identification purposes only.

      "},{"location":"manage-databases-and-caches/choreo-managed-mysql-databases/","title":"Choreo-managed MySQL Databases","text":"

      MySQL on Choreo offers fully managed, flexible relational databases on AWS, Azure, GCP, and Digital Ocean.

      "},{"location":"manage-databases-and-caches/choreo-managed-mysql-databases/#create-a-choreo-managed-mysql-database","title":"Create a Choreo-managed MySQL database","text":"

      Follow the steps below to create a Choreo-managed MySQL database:

      1. From the environment list on the header, located next to the Deployment Tracks list, select your Organization.
      2. In the left navigation menu, click Dependencies and then Databases.
      3. Click Create and select MySQL as the database type. Provide a display name for this server and follow the instructions.
      4. Select your preferred cloud provider from AWS, Azure, GCP, and Digital Ocean.
      5. Choreo uses the cloud provider to provision the compute and storage infrastructure for your database.
      6. There is no functional difference between databases created on different cloud providers, apart from changes to service plans (and associated costs).
      7. Choose the region for your database.
      8. Available regions will depend on the selected cloud provider. Choreo currently supports US and EU regions across all providers.
      9. Select the service plan.
      10. Service plans vary in the dedicated CPU, memory (RAM), storage space allocated for your database, the backup retention periods, and high-availability configurations for production use cases.
      "},{"location":"manage-databases-and-caches/choreo-managed-mysql-databases/#connect-to-your-choreo-managed-mysql-database","title":"Connect to your Choreo-managed MySQL database","text":"

      To connect to your Choreo-managed MySQL database, consider the following guidelines:

      • You can use any MySQL driver, ORM, or supported generic SQL library (may depend on the programming language) to connect to the database.
      • You can find the connection parameters in the Overview section in the Choreo Console under the relevant database.
      • MySQL databases accept traffic from the internet by default. You can restrict access to specific IP addresses and CIDR blocks under Advanced Settings.
      "},{"location":"manage-databases-and-caches/choreo-managed-mysql-databases/#high-availability-and-automatic-backups","title":"High Availability and Automatic Backups","text":"

      The high availability characteristics and the automatic backup retention periods for Choreo-managed MySQL databases vary based on your service plan as explained below:

      Service Plan High Availability Backup Retention Time Hobbyist Single-node with limited availability None Startup Single-node with limited availability 2 days Business Two-node (primary + standby) with higher availability 14 days Premium Three-node (primary + standby + standby) with highest availability 30 days

      In general, we recommend service plans for production scenarios for multiple reasons: - Provides another physical copy of the data in case of hardware, software, or network failures. - Typically reduces the data loss window in disaster scenarios. - Provides a quicker time to restore with a controlled failover in case of failures, as the standby is already installed and running.

      "},{"location":"manage-databases-and-caches/choreo-managed-mysql-databases/#automatic-backups","title":"Automatic Backups","text":"

      • Choreo runs full backups daily to automatically back up Choreo-managed MySQL databases and record binary logs continuously. Choreo encrypts all backups at rest.

      • Choreo automatically handles outages and software failures by replacing broken nodes with new ones that resume correctly from the point of failure. The impact of a failure will depend on the number of available standby nodes in the database.

      "},{"location":"manage-databases-and-caches/choreo-managed-mysql-databases/#connection-limits","title":"Connection Limits","text":"

      The maximum number of simultaneous connections to MySQL databases is fixed for each service plan and depends on how much RAM your service plan offers.

      Note

      An extra_connection with a value of 1 is added for system processes for all MySQL databases, regardless of the service plan.

      "},{"location":"manage-databases-and-caches/choreo-managed-mysql-databases/#for-plans-under-4-gib-ram","title":"For plans under 4 GiB RAM","text":"

      For plans under 4 GiB of RAM, the number of allowed connections is 75 per GiB:

      max_connections = 75 x RAM + extra_connection\n
      "},{"location":"manage-databases-and-caches/choreo-managed-mysql-databases/#for-plans-with-over-4-gib-ram","title":"For plans with over 4 GiB RAM:","text":"

      For plans with 4 GiB or more RAM, the number of allowed connections is 100 per GiB:

      max_connections = 100 x RAM + extra_connection\n
      "},{"location":"manage-databases-and-caches/choreo-managed-postgresql-databases/","title":"Choreo-Managed PostgreSQL Databases and Vector Databases","text":"

      PostgreSQL on Choreo offers fully Choreo-managed, efficient object-relational databases on AWS, Azure, GCP, and Digital Ocean. Additionally, Choreo allows you to create fully-managed PostgreSQL vector databases if you want to perform efficient vector similarity search.

      "},{"location":"manage-databases-and-caches/choreo-managed-postgresql-databases/#create-a-choreo-managed-postgresql-database","title":"Create a Choreo-managed PostgreSQL database","text":"

      Follow the steps below to create a Choreo-managed PostgreSQL database:

      1. Sign in to the Choreo Console at https://console.choreo.dev/.
      2. In the header, click the Organization list. This opens the organization home page.
      3. In the left navigation menu, click Dependencies and then Databases.
      4. Click Create and select PostgreSQL as the database type. Provide a display name for this server and follow the instructions.
      5. Select your preferred cloud provider from AWS, Azure, GCP, or Digital Ocean.
        • The cloud provider is used to provision the compute and storage infrastructure for your database.
        • There is no functional difference between databases created on different cloud providers, apart from changes to service plans (and associated costs).
      6. Choose the region for your database.
      7. Available regions will depend on the selected cloud provider. Choreo currently supports US and EU regions across all providers.
      8. Select the service plan.
      9. Service plans vary in the dedicated CPU, memory (RAM), storage space allocated for your database, the backup retention periods, and high-availability configurations for production use cases.
      "},{"location":"manage-databases-and-caches/choreo-managed-postgresql-databases/#create-a-choreo-managed-postgresql-vector-database","title":"Create a Choreo-managed PostgreSQL vector database","text":"

      Follow the steps below to create a Choreo-managed PostgreSQL vector database:

      1. Sign in to the Choreo Console at https://console.choreo.dev/.
      2. In the header, click the Organization list. This opens the organization home page.
      3. In the left navigation menu, click Dependencies and then Vector\u00a0Databases.
      4. Follow steps 4 onwards in the Create a Choreo-managed PostgreSQL database section.
      "},{"location":"manage-databases-and-caches/choreo-managed-postgresql-databases/#connecting-to-your-choreo-managed-postgresql-database","title":"Connecting to your Choreo-managed PostgreSQL database","text":"

      To connect to your Choreo-managed PostgreSQL database, consider the following guidelines:

      • You can use any PostgreSQL driver, ORM, or supported generic SQL library (may depend on the programming language) to connect to the database.
      • The connection parameters can be found in the Overview section in the Choreo Console under the relevant database.
      • PostgreSQL databases accept traffic from the internet by default. You can restrict access to specific IP addresses and CIDR blocks under Advanced Settings.
      "},{"location":"manage-databases-and-caches/choreo-managed-postgresql-databases/#high-availability-and-automatic-backups","title":"High Availability and Automatic Backups","text":"

      The high availability characteristics and the automatic backup retention periods for Choreo-managed PostgreSQL databases vary based on the selected service plan as shown below.

      Service Plan High Availability Backup Retention Time Hobbyist Single-node with limited availability None Startup Single-node with limited availability 2 days Business Two-node (primary + standby) with higher availability 14 days Premium Three-node (primary + standby + standby) with highest availability 30 days

      Service plans with standby nodes are generally recommended for production scenarios for multiple reasons: - Provides another physical copy of the data in case of hardware, software, or network failures. - Typically reduces the data loss window in disaster scenarios. - Provides a quicker time to restore with a controlled failover in case of failures, as the standby is already installed and running.

      "},{"location":"manage-databases-and-caches/choreo-managed-postgresql-databases/#automatic-backups","title":"Automatic Backups","text":"

      • Choreo runs full backups daily to automatically back up Choreo-managed PostgreSQL databases and copies the write-ahead logs (WAL) at 5-minute intervals or for every new file generated. Choreo encrypts all backups at rest.

      • Choreo automatically handles outages and software failures by replacing broken nodes with new ones that resume correctly from the point of failure. The impact of a failure will depend on the number of available standby nodes in the database.

      "},{"location":"manage-databases-and-caches/choreo-managed-postgresql-databases/#failure-recovery","title":"Failure Recovery","text":"

      • Minor failures: Choreo automatically handles minor failures such as service process crashes or temporary loss of network access in all plans without requiring significant changes to the service deployment. Choreo automatically restores the service to normal operation once Choreo automatically restarts the crashed process or when Choreo restores the network access.

      • Severe failures: To handle severe failures such as losing a node entirely in case of hardware or severe software problems, requires more drastic recovery measures. The monitoring infrastructure automatically detects a failing node, both when the node starts reporting issues in the self-diagnostics or when it stops communicating. In such cases, the monitoring infrastructure automatically schedules a new replacement node to be created.

        • In the event of database failover, the Service URI of your service remains the same; only the IP address will change to point to the new primary node.
        • Hobbyist and Startup plan provide a single node, and in case of failure, a new node starts up, restores its state from the latest available backup, and resumes serving traffic. In this plan, as there is just a single node providing the service, the service will become unavailable for the duration of the restoration. In addition, any write operations made since the backup of the latest WAL file will be lost. Typically, this time window is limited to either five minutes of time or one WAL file.
      "},{"location":"manage-databases-and-caches/choreo-managed-postgresql-databases/#connection-limits","title":"Connection limits","text":"

      The following connection limits apply to Choreo-managed PostgreSQL databases based on the selected service plan.

      Service Plan Max Connections Hobbyist 25 Startup/Business/Premium-4 100 Business-16 400 Premium-8 200"},{"location":"monitoring-and-insights/generate-custom-reports/","title":"Generate Custom Reports","text":"

      Choreo insights allow you to generate custom reports to view the information that is important to you to make timely decisions for the betterment of your business. With custom reports, you can generate reports for a set of metrics of your choice and aggregate results by specific fields. Once generated, the metrics can be filtered out using any selected group-by filters. Custom reports support three visualizations: overtime charts, pie charts, and tables.

      "},{"location":"monitoring-and-insights/generate-custom-reports/#metrics","title":"Metrics","text":"

      Choreo Insights allow you to retrieve data for the following metrics:

      • Successful Hit Count
      • Response Cache Hits
      • Request Mediation Latency
      • Response Mediation Latency
      • Backend Latency
      • Total Latency
      • API Errors
      • Target Errors
      "},{"location":"monitoring-and-insights/generate-custom-reports/#group-by","title":"Group-by","text":"

      Group-by fields specify how to group the metric data. e.g., You can select Successful Hit Count in the Metrics field and API Name under Group-by to retrieve the successful hit count grouped by the API name.

      Choreo Insights allow you to group metric data by the following fields:

      • API Name
      • API Version
      • API Resource Template
      • API Method
      • API Creator
      • Application
      • Application Owner
      • Destination
      • User Agent
      • Platform

      To generate a custom report, follow the steps below:

      1. In the left navigation menu, click Custom Reports.

      2. Select metric(s) from the Metrics drop-down selector.

      3. Select a minimum of 1 and a maximum of 3 group-by field(s) from the Group By drop down selector.

      4. Set the order of the group-by filters by drag and drop to determine the grouping order of the selected metric(s).

      5. Once you determine the order of the group-by fields, you can set values for each group-by field from the respective dropdown.

      6. Click Generate.

      "},{"location":"monitoring-and-insights/generate-custom-reports/#download-reports","title":"Download Reports","text":"

      Choreo Insights allow you to download report data related to each chart as a PDF or a CSV file.

      To do this, click the Download icon on the top right of the relevant chart and select the required file format.

      "},{"location":"monitoring-and-insights/insights-overview/","title":"Insights Overview","text":"

      Choreo provides comprehensive insights into APIs created within both the on-premises API Manager and the Choreo platform. Choreo insights provide a range of metrics, including API traffic, error rates, and latency, allowing you to monitor and optimize API performance effectively.

      With Choreo insights, you can:

      • Analyze API traffic: Monitor the volume of requests and responses to understand usage patterns.
      • Track errors: Identify and analyze errors to improve API reliability.
      • Monitor latency: Measure and optimize the response times of your APIs.
      • Generate reports: Generate detailed reports to keep stakeholders informed and support data-driven decision-making.
      • Configure alerts: Set up alerts for specific events or thresholds to proactively manage API performance.
      • Obtain granular insights: Obtain detailed information on a per-application, per-API, and per-user basis for more targeted analysis.
      • Drill down into data: Dive deeper into data to perform root cause analysis.

      By leveraging these insights, businesses can make informed decisions to enhance their API strategies and drive their digital transformation initiatives forward.

      "},{"location":"monitoring-and-insights/insights-overview/#view-insights","title":"View insights","text":"

      To view usage insights, go to the Choreo Console and click Usage Insights in the left navigation menu.

      If you are viewing insights on the Choreo platform at the organization level, note the following:

      • Permission-based access: Signed-in users can only view insights for components or projects that they have permission to access.
      • Data exclusion: Insights exclude data from components you cannot access and the data related to deleted components.
      • Comprehensive view permission: To view insights for all components, including deleted ones, across the organization regardless of project visibility, you must have the View Organization Insights permission under OBSERVABILITY-MANAGEMENT with the mapping level defined at the Organization level.
      • Admin role: Users with the admin role have the View Organization Insights permission by default and can view organization-wide insights.
      • Configuring permissions: For detailed steps on configuring permissions, see Control Access in the Choreo Console.

      By ensuring proper permissions are set, organizations can manage access to insights effectively while maintaining data security and relevance.

      "},{"location":"monitoring-and-insights/insights-overview/#analyze-statistics","title":"Analyze statistics","text":"

      Once you access the Usage Insights page, you can access the following subpages.

      "},{"location":"monitoring-and-insights/insights-overview/#overview","title":"Overview","text":"

      The Overview page gives you a quick overview of the system status.

      The information displayed is as follows:

      • Total Traffic

        This widget displays the total traffic of the selected environment received during a given time interval. Both successful requests and failed requests are displayed. To investigate further, you can click the arrow icon on the bottom right corner of the widget to open the Traffic page.

      • Error Request Count

        This widget displays the total number of requests that have resulted in errors in your selected environment during the selected time range.

      • Average Error Rate

        This widget displays the average error rate (i.e., error count/total request count) of the selected environment for a given time interval. You can use this widget as an indicator to understand the health of the system. If the error rate is high, you can investigate further by clicking the arrow on the bottom right of the widget and opening the Errors page.

      • 95th Percentile Latency

        This widget displays the 95th percentile of all API latencies in your selected environment for the given time interval. You can use this widget to know whether the complete system operates under given SLAs. This metric provides the first indication of slow APIs. To investigate further, you can click the arrow on the bottom right of the widget to open the Latency page where you can further analyze the latency.

      • API Request Summary

        This chart displays the total successful requests, the total requests that have resulted in errors, and the latency in a timeline. The y-axis on the left displays the request count and the error count. The x-axis shows time, and the y-axis on the right shows the latency in milliseconds. The granularity of the data points is decided based on the time range you have selected. The tooltip provides the exact value of all three metrics accurately.

      "},{"location":"monitoring-and-insights/insights-overview/#traffic","title":"Traffic","text":"

      The Traffic page shows information related to the traffic that goes through your API management deployments. This includes API usage, application usage, resource usage, etc. You can use this page to investigate the usage of APIs and applications, traffic patterns, etc.

      You can filter the information displayed in the widgets as follows:

      Filtering Option Description By API In the API field, you can select one or more APIs for which you want to view analytics. All is selected by default. Once you select an API, you can further filter by a specific application that uses the selected API via the Application field described below. By Application In the Application field, you can select the applications for which you want to view analytics. All is selected by default. The available applications are all the applications that have subscribed to one or more of the APIs you selected in the API field.

      You can view the following information for the APIs you have selected using the above filtering criteria:

      • API Usage Over Time

        This timeline shows the count of API hits for the APIs for the filtered APIs. If multiple APIs are selected, the timeline shows each API in a separate line with a legend separating each line. You can also zoom in on a selected time range by selecting that area in the chart. To restore to the original view use the Zoom out button on the top right-hand corner of the plot.

      • API Usage By Application

        This widget shows the per-application breakdown of requests for the APIs you selected. You can use the pie chart view or the line chart view. You can switch between the two views using the small icon at the upper-right corner of the widget.

      • API Usage By Target

        This widget shows the per-backend breakdown of requests for the APIs you selected. This information is useful when multiple APIs share the same backend that has traffic restrictions. You can use these stats to scale your backends proactively. You can switch between the two views using the small icon at the upper-right corner of the widget.

      • API Resource Usage

        This table shows a resource-level breakdown of API traffic. Each row represents an API resource and it shows the API name, resource path, API method, and the hit count for that combination.

      "},{"location":"monitoring-and-insights/insights-overview/#errors","title":"Errors","text":"

      The Errors page shows information related to erroneous API calls that are received by your system. The errors are categorized based on the error type. You can further drill down using the error subtypes. Use this page as the starting point for debugging any API errors.

      You can filter the information displayed in the widgets as follows:

      Filtering Option Description By API In the API field, select the APIs for which you want to view analytics. By default, all APIs are selected. You can select one or multiple APIs from this selector and view the aggregated result. By Category The Category field is displayed when you click Category in the upper right corner of the page. In this field, you can select one or all of the following error categories:Authentication: Any kind of authentication error falls into this category including expired/missing/invalid credentials.Target Connectivity: Any kind of back-end error falls into this category including connection time-outs/other back-end errors (for example, 4xx and 5xx status codes).Throttling: Any request that fails due to rate-limiting falls into this category including application throttling/subscription throttling.Other: All other errors fall into this category including mediation errors/resource not found errors. By Status Code The Status Code field is displayed when you click Status Code in the upper right corner of the page. In this field, you can select all or any available HTTP status code categories (4xx, 5xx, etc.). These status codes represent the response status of the API Gateway. Viewing errors by category

      The following widgets are available for monitoring errors when you have selected Category in the upper-right corner of the page.

      • This graph shows the error by category over time for the selected period. Apply the required filters as explained above to select the APIs and the error categories to which this content applies. When you select multiple APIs, the error count is grouped by category.

      • This table provides further information about the errors such as application details and the error reason. For some authentication errors, the application name is not available. You can use this table to get more concrete information about the errors related to your APIs and then start the problem identification.

      Viewing errors by status code

      The following widgets are available for monitoring errors when you select Status Code in the upper-right corner of the page.

      • Errors by Status Code

        This graph shows the distribution of HTTP status codes received for errors over time for the selected period. Apply the required filters as explained above to select the APIs and status code groups to which this content applies. When you select multiple APIs, the error count is grouped by the status code.

      • Target Errors by Status Code

        This graph shows the distribution of target errors that have occurred during the selected time interval by HTTP status code. Apply the required filters as explained in the table above to view the APIs and status code groups to which this content applies. If you select multiple APIs, the widget groups the target error count by the status code.

      • Errors

        The Errors heat map shows the HTTP response codes of errors sent to the client by the API Gateway. Each row displays the number of times the system returned each status code for the selected APIs. The cell color is red for higher numbers and white for lower numbers. If required, you can further filter the results by the error code groups you identified with the Errors by Status Code graph.

      • Target Errors

        The Target errors heat map shows the HTTP response codes of errors that the API Gateway received from the backend. Each row displays the number of times the system returned each status code for the selected APIs. The cell color is red for higher numbers and white for lower numbers. If required, you can further filter the results by the error code groups you identified with the Target Errors by Status Code graph.

      "},{"location":"monitoring-and-insights/insights-overview/#latency","title":"Latency","text":"

      The Latency page shows information related to the latency of API calls within the API management deployment. You can view a summary of the slowest APIs and then drill down into the API view for further analysis. Use this page as a starting point to debug API slowness.

      The information displayed is as follows:

      • Top 10 Slowest APIs

        This widget allows you to identify the slowest APIs of the API management system at a glance. Since these are the APIs that contribute to the higher 95th percentile of the system, improving these APIs lowers the 95th percentile of latency in the API Management deployments.

      • Latencies By Category

        This widget allows you to further drill down details in the above chart. Use the API selector in this widget to select the slow API you identified in the earlier step and then analyze further. Use the charts available in the widget to view the 95th percentile and the median latency over the selected period of the following:

        • Backend
        • Request mediation
        • Response mediation

      You can use these charts to further drill down and analyze whether the latency occurs in the backend, request mediation, or response mediation. Also, because you can see both the median and 95th percentile, you can easily identify whether the slowness is occurring in each request or whether it is intermittent.

      "},{"location":"monitoring-and-insights/insights-overview/#cache","title":"Cache","text":"

      The Cache page shows statistics that indicate the efficiency with which response caching is carried out for the requests sent to your APIs.

      The page displays the following statistics:

      • Cache Hit Percentage

        This graph shows the percentage of requests the system has handled via the response cache over time and the total hits over time. This information allows you to assess how efficiently the backend handles API requests. For example, if the cache hit rate is low, it may indicate that the backend generates the same response each time a specific request is sent instead of returning the response via the cache. In such a scenario, there is scope to improve performance via response caching.

      • Latency

        This section shows the total latency reported during the same time interval applied to the Cache Hit Percentage graph above.

      "},{"location":"monitoring-and-insights/insights-overview/#devices","title":"Devices","text":"

      The Devices page displays information about operating systems and HTTP agents that end users use to invoke the APIs. You can use this page to get an idea of the distribution of your user base and improve your APIs to match the audience.

      To filter the information displayed on this page by API, select the required API(s) in the API field. All is selected by default.

      The information displayed is as follows:

      • Top Platforms

        This chart shows the breakdown of the API clients by the operating system. The pie chart only shows platforms with a significant amount of requests. Other platforms are grouped under the Other category.

      • Top User Agents

        This chart shows the breakdown of the API clients by user-agent. The pie chart only shows user agents with a significant amount of requests. Other platforms are grouped under the Other category.

      "},{"location":"monitoring-and-insights/insights-overview/#alerts","title":"Alerts","text":"

      The Alerts page shows information related to business alerts issued by Choreo for your currently selected environment and organization. You can use this page as a health monitoring dashboard and make it visible to your project team. Using this page you can drill down on each alert and discover possible anomalies in your published APIs. See the topics given below to get details of the available widgets and understand how to use them effectively.

      Prerequisites

      To use this page, be sure to configure alerts and have API invocations that trigger alerts.

      Note

      Alerts are retained only for a week.

      • Alert Summary

        This table lists each alert generated during the selected time interval. The message of the alert can be viewed by expanding the arrow icon on the details column. The drop-downs can be used to filter alerts based on the alert type and API.

      • Top APIs by Alert Count

        This shows a pie chart and a table to visualize the alert distribution during the selected time interval.

      "},{"location":"monitoring-and-insights/insights-overview/#reports","title":"Reports","text":"

      The Reports page allows you to download monthly usage reports for your system. There are preconfigured reports with system-wide statistics, and a custom report generator to generate reports based on a subset of APIs/applications.

      Download custom reports

      This widget allows you to generate a custom report for the statistics that have been generated up to now and download it.

      To generate a custom report, follow the steps below:

      1. In the API field, select one or more APIs for which you want to generate the report. If required, you can select all the APIs by selecting All.

      2. If you need to further filter the content printed in the report, select one or more applications in the Application field. By default, all the applications that have subscribed to one or more of the selected APIs are selected.

        Tip

        If you want to filter the report content by the API consumer instead of the application, click on the toggle switch to the right of the Application field, and then select the required consumer. Only consumers who have subscribed to one or more of the selected APIs are displayed in the list. You can either select one or all of them.

      3. Select the required year and the month in the Year and Month fields to specify the time interval for which you want to generate the report.

      4. Click Download, and select the required format.

      The report is downloaded in the specified format. The following is a sample report generated in PDF format.

      The contents of the report are as follows.

      Item Description Generated Time The date and the time the report was generated. Organization The organization to which the report applies. Each report always applies to a specific organization. Environment The environment to which the report applies. Each report always applies to a specific environment. Tenant The tenant to which the report applies. Each report always applies to a specific tenant. Reporting period The time interval for which the report is generated. Total request count The total request count received by all selected APIs during the report time interval.

      The table in the report contains the following rows.

      Item Description API The name of the API. Application The name of the application. The name of the subscriber is also provided within brackets. Usage The usage count. Download pregenerated reports

      These widgets allow you to download monthly reports for the last three months.

      To download a pregenerated report, click Download for the relevant month and then click on the required format.

      "},{"location":"monitoring-and-insights/insights-overview/#geo-map","title":"Geo Map","text":"

      The Geo Map page allows you to see a geographical representation of your API usage. You can use this page to make business decisions such as identifying growing regions, analyzing the impact of a region-specific marketing campaign, etc.

      To filter the information displayed on this page by API, select the required API(s) in the API field. The default value is All.

      This heat map highlights the countries with the appropriate color based on the hit count. It uses a relative color scale to depict the highest hit count to the lowest non-zero hit count.

      Viewing the number of requests by country

      You can hold the pointer over the highlighted countries to view the country name and the total number of hits from that location. You can also use the mouse to zoom the map or pan it. Optionally, you can download geo-map data in a tabular format using the PDF or CSV download options by clicking on the top right corner.

      Note

      • Currently, this feature is only available for on-premises environments.
      • The geo-map page utilizes the IP address of the incoming request to derive the geolocation. The actual source IP address can be replaced if there are intermediate hosts between the client and the gateway node. Therefore, the reverse proxy or the load balancer fronting the gateway node must add the x-forwarded-for header to each request to preserve the source IP address. If you do not configure this correctly, the Geo Map page will not show any data. To test this, you can manually add an x-forwarded-for header to the request.
      "},{"location":"monitoring-and-insights/integrate-choreo-with-moesif/","title":"Integrate Choreo with Moesif","text":"

      Moesif is an API analytics and monetization service that helps you grow your API products. You can integrate Choreo with Moesif and gain valuable insights into your API's usage. While Moesif's API analytics capabilities empower you to make informed decision-making on behalf of your organization, its monetization options simplify revenue generation from your APIs, eliminating the need for complex coding.

      In this guide, you will:

      • Generate a key in Moesif.
      • Configure Choreo to connect to Moesif.
      • Invoke an API and observe the insights on the Moesif dashboard.
      "},{"location":"monitoring-and-insights/integrate-choreo-with-moesif/#step-1-generate-an-api-key-in-moesif","title":"Step 1: Generate an API key in Moesif","text":"

      Let's generate an API key in Moesif. If you're an existing Moesif user with a registered organization, proceed to step 1.2.

      "},{"location":"monitoring-and-insights/integrate-choreo-with-moesif/#step-11-generate-a-key-in-moesif-as-a-new-user","title":"Step 1.1: Generate a key in Moesif as a new user","text":"

      If you are a new user, follow the steps below to register an organization and generate a key:

      1. Go to https://www.moesif.com/.
      2. Click Sign Up and select an authentication option and proceed.

      3. On the Get Started page, enter meaningful values for the fields and create a new organization.

        Field Description Organization Name The name of your company or team. Application Name The name of your application that represents one project or environment.

      4. Click Next.

      5. On the Overview page, click Next.

        This opens the Quick Install page. As there is no data, you cannot proceed. Let's configure Moesif to receive data from Choreo.

      6. Select a WSO2 Choreo as the Server Integration

      7. Copy the Application Id.

      "},{"location":"monitoring-and-insights/integrate-choreo-with-moesif/#step-12-access-the-api-key-in-moesif-as-an-existing-user","title":"Step 1.2: Access the API key in Moesif as an existing user","text":"

      If you are an existing user with a registered organization, or you do not have an API key for the organization you created, follow the steps below to access the generated API key:

      1. Go to https://www.moesif.com/.
      2. Click on your profile in the bottom left corner, and navigate to the API Keys page.
      3. Copy the Collection Application Id.
      "},{"location":"monitoring-and-insights/integrate-choreo-with-moesif/#step-2-integrate-choreo-with-moesif","title":"Step 2: Integrate Choreo with Moesif","text":"

      Let's configure Choreo to publish events to Moesif.

      1. Go to https://console.choreo.dev/ and sign in.
      2. On the left navigation, click Settings.
      3. In the header, click the Organization list. This will open the organization level settings page.
      4. Click the API Management tab, and click Moesif Dashboard.
      5. Select the environment you want to publish data for.
      6. Paste the Application Id you copied.
      7. Click Add.

      Once you successfully add the key, you will see a delete option next to it. Currently, you can only configure one API key. If you need to add a new API key, you need to delete the existing key and add the new one.

      Note

      Once you configure the Moesif API key on Choreo, wait for five minutes before you publish any data to the Moesif API analytics platform.

      "},{"location":"monitoring-and-insights/integrate-choreo-with-moesif/#step-3-invoke-an-api-and-observe-the-data-on-the-moesif-dashboard","title":"Step 3: Invoke an API and observe the data on the Moesif Dashboard","text":"

      You have configured Choreo to publish data to Moesif. Let's see how you can view the insights on Moesif.

      Tip

      • If you have not created an API and deployed it on Choreo, you can follow the create and deploy a REST API guide to get started.

      1. Invoke your API by following the Test REST Endpoints via the OpenAPI Console guide.

      2. Once you publish data, your Moesif dashboard will receive events. Once Moesif receives events, you will see a notification on Moesif confirming that it received data.

      3. Click Next on the notification. This will take you to the final step, where you can opt to add team members. In this guide, let's skip this step.

      4. Click Finish.

      You can now view your API's insights in the Moesif dashboard.

      "},{"location":"monitoring-and-insights/observability-overview/","title":"Observability Overview","text":"

      The Choreo observability dashboard provides a comprehensive interface to visualize and monitor the performance of services deployed on Choreo.

      The Observability dashboard allows you to:

      • Observe the throughput and latencies of requests served over a given period.
      • Compare metrics side-by-side to facilitate efficient diagnosis.
      • Observe the diagnostics view generated over a given period.
      • View logs generated over a specific timeframe.

      Tip

      If you are a Choreo private data plane customer and you want to observe your private data plane using New Relic, see Observing Choreo Private Data Planes With New Relic.

      "},{"location":"monitoring-and-insights/observability-overview/#throughput-and-latency-graphs","title":"Throughput and latency graphs","text":"

      The throughput graph depicts the throughput of requests per second for a selected timestamp.

      By default, Choreo renders this graph for the data generated within the past 24 hours. You can change the default time window by selecting the time range and zone from the options bar. To expand the graph, click and drag the cursor over the period you want to drill down.

      You can view the Choreo service logs in the Logs pane below the throughput and latency graph. Clicking on a graph updates the Logs view to contain the corresponding log entries generated at that time. You can use these logs to identify the reasons for any latency and throughput anomalies you detect using the graph.

      "},{"location":"monitoring-and-insights/observability-overview/#diagnostics-view","title":"Diagnostics view","text":"

      The Diagnostics view allows you to simultaneously analyze errors, throughput, latencies, CPU usage, memory usage, and logs for a particular event. This facilitates detailed error detection and analysis.

      By default, the time range selected for the Throughput & Latency graphs is the same time range used for the Diagnostics view.

      Each horizontal section of the graph, termed a bin, represents a specific period and comprises:

      • Date/Time: Indicates when the log entries began to appear.
      • Logs: List of log entries and respective log counts within the bin's timeframe, sorted by precedence (error logs followed by info logs). Each bin displays a maximum of five log entries.
      • Error: The number of HTTP errors that occurred at the selected time.
      • TP: Throughput of the requests at the selected time (req/s).
      • Latency: Request latency at the selected time (ms).
      • CPU: CPU usage at the selected time (millicores).
      • Memory: Memory usage at the selected time (MiB).
      "},{"location":"monitoring-and-insights/observability-overview/#logs","title":"Logs","text":"

      The Logs pane serves as a centralized view to observe logs of the components you deploy on Choreo. This facilitates rigorous troubleshooting and analysis.

      "},{"location":"monitoring-and-insights/view-logs/","title":"View Logs","text":"

      The unified log view in Choreo allows you to view runtime and audit logs to gain application and user insights while ensuring data privacy.

      Choreo provides real-time insights through live logs and allows you to view historical logs for insights into the past. You also have the flexibility to define a required time range to view relevant log entries, where an intuitive scrolling capability facilitates easy viewing of appropriate logs within the selected time frame.

      The log view also provides advanced filtering capabilities that allow you to efficiently navigate through appropriate logs to expedite troubleshooting in distributed environments.

      Note

      All personally identifiable information (PII) gets resolved at the frontend service level, with only relevant UUIDs stored in logs.

      "},{"location":"monitoring-and-insights/view-logs/#runtime-logs","title":"Runtime logs","text":"

      Choreo runtime logs provide insights into both project and component-level logs, covering application and gateway logs. These logs streamline the debugging process by centralizing diverse log sources.

      In Choreo, any organization member can view runtime logs via the runtime logs page. Choreo allows you to apply filters based on parameters such as log level (error, warn, info, debug), log type (application, gateway), and environment (development, staging, production) to simplify the debugging process.

      To access runtime logs, follow the steps below:

      1. Sign in to Choreo.

      2. In the left navigation menu, click Observability and then click Runtime Logs. This displays runtime logs for the past 30 days by default.

        To view logs based on a specific time range and other requirements, you can apply the necessary filter criteria.

      "},{"location":"monitoring-and-insights/view-logs/#understand-runtime-logs","title":"Understand runtime logs","text":"

      When you view component-level logs on the Runtime Logs page, you will see both application and gateway logs.

      Application logs

      Each application log entry displays the following details:

      • timestamp: The time when the request is received by the component.
      • level: Indicates the severity of the log message. Possible values are Debug, Info, Warn, and Error.
      • componentVersion: The version of the invoked component.
      • componentVersionId: The identifier of the invoked component\u2019s version.
      • envName: The environment of the inbound request. For example, Development, Production, etc.
      Gateway logs

      Each gateway log entry displays the following details:

      • timestamp: The time when the request is received by the gateway component.
      • logLine: Contains the following details about the request, including inbound and outbound information from the gateway perspective.
        • Method: The HTTP method of the request.
        • RequestPath: The path of the inbound request.
        • ServicePath: The path of the outbound request.
        • UserAgent: The user-agent header of the request.
        • CorrelationID: The request identifier of the inbound request. This is useful to track a request.
        • ServiceHost: The host IP of the backend.
        • Duration: The time taken for the gateway to serve the request.\u00a0\u00a0

      • gatewayCode: Indicates the state of the request from the gateway perspective. Possible values are as follows:

        • BACKEND_RESPONSE: Indicates successful processing of the request by the gateway with a response to the client from the backend application.
        • CORS_RESPONSE: Denotes a CORS (Cross Origin Resource Sharing) request.
        • AUTH_FAILURE: Indicates a request failure at the gateway due to authentication or authorization issues, such as an invalid token.
        • NO_HEALTHY_BACKEND: Indicates a request failure at the gateway due to a non-existent backend.
        • RATE_LIMITED: Indicates a request failure at the gateway due to surpassing the rate limit enforced within the component.
        • RESOURCE_NOT_FOUND: Indicates a request failure at the gateway due to the absence of a matching API resource for the inbound request. This can be caused by a mismatch in the HTTP method, path, or host.
        • BACKEND_TIMEOUT: Indicates a request timeout when calling the backend application from the gateway.
        • GATEWAY_ERROR: Indicates a request failure due to an erroneous behavior in the gateway.

        Note

        Occasionally, a request may not fit into any of the above categories. In such instances, the gatewayCode is displayed as UNKNOWN.

      • statusCode: The HTTP status code returned to the client.

      • componentVersion: The version of the invoked component.
      • envName: The environment of the inbound request. For example, Development, Production, etc.
      "},{"location":"monitoring-and-insights/view-logs/#audit-logs","title":"Audit logs","text":"

      Audit logs, also called audit trails, enhance security, ensure compliance, provide operational insights, and help manage risks.

      In Choreo, an audit log records organization-level user-specific operations performed via the Choreo Console. It also captures the timestamp and the outcome of the action.

      As of now, Choreo captures the following user-specific operations as audit logs:

      • Project creation, update, and deletion.
      • Component creation, update, and deletion.
      • Component promotion initiation.
      • Component version creation.
      • Component deployment, redeployment, and undeployment initiation for all components other than REST API Proxy components.
      • Component API access mode update.
      • Enabling and disabling component auto-deployment on commit.
      • Component build configuration update.
      • Component endpoint creation, update, and deletion.
      • Organization user management.
      • On-premises key management.
      • Project-level configuration management.

      In Choreo, organization administrators are allowed to view audit logs by default. If other members need to access organization-specific audit logs, the administrator can create a role with the relevant permission and assign it to members. For step-by-step instructions on how to create and assign a role with relevant permission, see Manage audit log access.

      To view audit logs, follow these steps:

      1. Sign in to Choreo.

      2. In the Choreo Console, go to the top navigation menu and click Organization.

        Tip

        As of now, you can only view organization-level audit logs.

      3. In the left navigation menu, click DevOps and then click Audit Logs. This displays audit logs for the past 30 days by default.

        To view audit logs based on a specific time range and other requirements, you can apply the necessary filter criteria.

      "},{"location":"monitoring-and-insights/view-logs/#audit-log-retention","title":"Audit log retention","text":"

      Choreo retains audit logs for one year and archives them for an additional year. Therefore, the total retention period for audit logs is two years.

      "},{"location":"monitoring-and-insights/view-logs/#manage-audit-log-access","title":"Manage audit log access","text":"

      Follow the steps given below to create a role with audit log access permission and assign it to organization members who need access to audit logs:

      Note

      You must be the organization administrator to perform this action.

      Step 1: Create a role with audit log access permission
      1. In the Choreo Console, go to the top navigation menu and click Organization.
      2. In the left navigation menu, click Settings.
      3. On the Organization tab, click Roles and then click + Create Role.

      4. Enter a name and description for the role.

      5. Click Next.

      6. In the Create Role dialog, select LOG-MANAGEMENT under Permissions.

      7. Click Create.

      Step 2: Assign the created role to an organization member
      1. On the Organization tab, click Members. This lists the members of the organization with their respective details.

      2. Click on a member who needs to have access to audit logs, and then click + Add Role.

        Tip

        If you want to invite one or more members and assign them the audit log viewer role, follow the steps given below:

        1. Click + Invite Member and then click to expand the Roles list.
        2. Select the role you created in Step 1.
        3. In the Emails field, enter the email addresses of members you want to invite and grant permission to access audit logs.
        4. Click Invite. This sends an invitation email to each email address so that the members can accept and obtain access to view audit logs.

      3. Click to expand the Roles list and select the role you created in Step 1.

      4. Click Add. This assigns the selected role to the member.
      "},{"location":"monitoring-and-insights/alerts/configure-alerts/","title":"Configure Alerts","text":"

      This section explains how you can configure alerts for your API manager deployments. Setting up alerts allows you to proactively monitor your API ecosystem and take corrective measures when necessary.

      You can configure alerts for each environment within your organization. You can add, modify, or delete alerts per API. Optionally, you can specify a list of emails for each alert configuration.

      Alerts are subject to a suppression policy to prevent duplicate notifications within a specific time frame. By default, a 10-minute suppression window is applied, and this is not configurable. The suppression policy is specific to each alert configuration.

      Info

      • You can configure a maximum of 20 alerts per organization, environment, and tenant combination.
      • Adding email addresses to an alert configuration is optional. If necessary, you can add a maximum of 5 email addresses per alert.

      Alerts can be categorized as either latency alerts or traffic alerts.

      "},{"location":"monitoring-and-insights/alerts/configure-alerts/#latency-alerts","title":"Latency alerts","text":"

      Latency alerts notify you if the response latency of an API exceeds a predefined threshold. This is useful for APIs that need to meet specific SLAs and for proactively identifying slow APIs.

      To configure a new latency alert, follow the steps given below:

      1. Sign in to the Choreo Console.
      2. Ensure you are in the correct organization where you have a project with the API to configure a latency alert.
      3. In the Choreo Console left navigation menu, click Usage Insights.
      4. In the left navigation menu on the Usage Insights page, click Alerts.
      5. Click the Environment list and select the required environment.

      6. Click Alert Configuration.

        This opens the Alert Configuration pane with the Latency tab open by default.

      7. In the API Name field, select the API for which you want to configure the alert.

        Info

        Only the APIs that you have invoked at least once are listed here. For other APIs, you need to give the API name in the required format as instructed in the UI.

      8. In the Metric field, select the required metric against which you want to evaluate the alert configuration.

        Tip

        The list includes all available options. If there are multiple metrics, you can select the required metric. If there is only one metric to choose, that metric is selected by default, and the field is disabled.

      9. In the Latency field, specify the threshold in milliseconds.

        Info

        When the 95th percentile of the selected metric exceeds the threshold provided here, alerts are triggered.

      10. In the Emails field, specify the list of emails that should be notified when the alert is added.

      11. Click + Add.

      Once an alert is successfully added, the alert configuration is listed in the Alert Configuration pane. Each configuration can be edited and removed via this pane.

      "},{"location":"monitoring-and-insights/alerts/configure-alerts/#traffic-alerts","title":"Traffic alerts","text":"

      Traffic alerts notify you when the request count of an API exceeds a predefined threshold. This is useful for managing APIs with backend traffic limits or monetized backends that require proactive scaling based on incoming traffic.

      To configure a new traffic alert, follow the steps below:

      1. Sign in to the Choreo Console.
      2. Ensure you are in the correct organization where you have a project with the API to configure a latency alert.
      3. In the Choreo Console left navigation menu, click Usage Insights.
      4. In the left navigation menu on the Usage Insights page, click Alerts.
      5. Click the Environment list and select the required environment.
      6. Click Alert Configuration. This opens the Alert Configuration pane.
      7. Click the Traffic tab.

      8. In the API Name field, select the API for which you want to configure the alert.

        Info

        Only the APIs that you have invoked at least once are listed here. For other APIs, you need to give the API name in the required format as instructed in the UI.

      9. In the Metric field, select the required metric against which you want to evaluate the alert configuration.

        Tip

        The list includes all available options. If there are multiple metrics, you can select the required metric. If there is only one metric to choose, that metric is selected by default, and the field is disabled.

      10. In the Threshold field, specify the threshold number of requests per minute.

      11. If required, specify the list of emails that should be notified when the alert is generated in the Emails field.

      12. Click Add.

      Once an alert is successfully added, the alert configuration is listed in the Alert Configuration pane. Each configuration can be edited and removed via this pane.

      "},{"location":"monitoring-and-insights/delivery-insights/configure-dora-metrics/","title":"Configure CIO Dashboard","text":"

      You can view DORA metrics in Choreo to use as KPIs to measure your organization's DevOps team's performance. Choreo enables this feature by default for all organizations. DORA includes the following four key metrics that are regarded as the most important metrics to indicate team performance:

      • Deployment Frequency: How often an organization successfully releases to production
      • Lead Time for Changes: The amount of time it takes a commit to get into production
      • Change Failure Rate: The percentage of deployments causing a failure in production
      • Time to Restore Service: How long it takes an organization to recover from a failure in production

      Choreo enables two DORA metrics by default; deployment frequency and lead time for change.

      "},{"location":"monitoring-and-insights/delivery-insights/configure-dora-metrics/#configure-the-cio-dashboard-with-all-metrics","title":"Configure the CIO Dashboard with all metrics","text":"

      To configure the CIO dashboard by enabling the other two metrics, follow the steps below:

      1. Sign in to Choreo using your Google, GitHub, or Microsoft account.
      2. On the left navigation menu, click Delivery Insights.
      3. Click on the DORA Metrics tab.
      4. Scroll to the bottom of the dashboard and click Configure.
      5. Select your incident management system. Currently, Choreo only supports GitHub.
      "},{"location":"monitoring-and-insights/delivery-insights/configure-dora-metrics/#configuring-github-as-the-incident-management-system","title":"Configuring GitHub as the incident management system","text":"

      To configure GitHub as the incident management system, follow the steps below:

      "},{"location":"monitoring-and-insights/delivery-insights/configure-dora-metrics/#step-1-authorize","title":"Step 1: Authorize","text":"

      First, let's authorize Choreo to access the repositories used to record incidents.

      On the Add Integration page, select GitHub and click Authorize with GitHub.

      Once the authorization process is complete, you can start configuring the GitHub repository.

      "},{"location":"monitoring-and-insights/delivery-insights/configure-dora-metrics/#step-2-configure","title":"Step 2: Configure","text":"

      By default, Choreo collects incident details(issues) from all repositories containing Choreo components. However, you can configure a GitHub account and a GitHub repository to allow Choreo to read issues from a specific repository, and then click Next.

      Field Description Value Data Plane Choreo collects incident details by running a scheduled job which invokes the GitHub API periodically. This job runs on the user's data plane. This configuration allows users to specify a preferred data plane to run the job, especially when they have multiple data planes. Select a preferred data plane from the Data Plane list. GitHub Account The GitHub account you have your repositories in. Select your GitHub account that includes the repository used for incident collection. GitHub Repository By default, Choreo will collect incident details(issues) from all repositories that already have Choreo components."},{"location":"monitoring-and-insights/delivery-insights/configure-dora-metrics/#step-3-filter-label","title":"Step 3: Filter label","text":"

      The filter label allows Choreo to scrape issues associated with that label.

      • Incident Label: The label Choreo uses to identify incidents. For example, Type/Incident.

      • Invalid incident label(Optional): Choreo will not scrape issues with this label and will proceed to skip these issues. For example, Resolution/Invalid. You can use this label when you want to ignore issues. For example, closing an issue after identifying that it doesn't qualify as an incident issue as it was due to a user error.

      Once you configure the labels, click Save.

      Choreo will enable incident data publishing in the background once you save. Once completed, DORA metric charts will appear in the CIO dashboard for Mean Time To Recover and Change Failure Rate. If there are any issues in the configuration, the configure banner will reappear, and the user can proceed to reconfigure.

      "},{"location":"monitoring-and-insights/delivery-insights/configure-dora-metrics/#step-4-enrich-incident-tickets-with-deployment-information","title":"Step 4: Enrich incident tickets with deployment information","text":"

      Choreo extracts deployment information from the relevant incident and generates DORA metrics that help you analyze the deployment statistics related to the incidents. Therefore, you must manually update the GitHub issue with the relevant deployment-related information. Follow the steps below to add the deployment information to the GitHub issue.

      Get deployment details
      1. On the Choreo Console header, select the project and the component for which the incident was reported.
      2. On the left navigation menu, click Deploy.
      3. On the Production Environment card, click Deployment History.

      4. On the right-hand side panel, select the relevant deployment, and click Release details to copy the deployment details to the clipboard.

      Add deployment information to the GitHub issue
      1. Edit the GitHub issue to add the deployment information.
      2. Paste the deployment information you copied (in step 4 under the section Get deployment details) at the end of the issue body.
      3. Click Save.

      That's it! You have successfully configured your CIO dashboard to include the DORA metrics.

      Note

      The CIO Dashboard is expected to reflect the latest statistics within approximately 30 minutes.

      "},{"location":"monitoring-and-insights/delivery-insights/configure-dora-metrics/#edit-configurations","title":"Edit configurations","text":"

      You can edit or override the configurations you made via the edit option in the dashboard.

      "},{"location":"monitoring-and-insights/delivery-insights/view-dora-metrics/","title":"View DORA metrics","text":"

      DORA metrics comprise four key metrics. Let's explore what each metric represents in Choreo. Choreo displays a summary and graphical representation of each metric.

      "},{"location":"monitoring-and-insights/delivery-insights/view-dora-metrics/#snapshot-view","title":"Snapshot view","text":"

      The snapshot view includes four tiles on the top of the dashboard, summarizing DORA metrics for the entire time period you select. The snapshot view categorizes each metric into four performance levels: elite, high, medium, and low. The categorization is based on the 2020 DORA metric report.

      "},{"location":"monitoring-and-insights/delivery-insights/view-dora-metrics/#time-series-view","title":"Time series view","text":"

      The time series view provides a graphical representation of how the statistics have changed over a period of time. You can use this view to analyze team performance and identify trends.

      "},{"location":"monitoring-and-insights/delivery-insights/view-dora-metrics/#deployment-frequency","title":"Deployment frequency","text":"

      DORA team definition: The frequency at which an organization successfully releases to production.

      In Choreo, this translates to the number of times an organization deploys a component to the production environment. Choreo does not count the deployment done to the development or other lower environments.

      "},{"location":"monitoring-and-insights/delivery-insights/view-dora-metrics/#snapshot-view_1","title":"Snapshot view","text":"

      The snapshot view of the Deployment Frequency metric shows the deployment frequency for all components within the selected organization. The frequency is dynamically determined and rounded to the nearest measurement. For example, if there is more than one deployment daily, the deployment frequency is measured in deployments per day. If the deployment frequency is less, it is measured in a higher granularity. For example, deployments per week.

      A lower deployment frequency indicates that your organizational efficiency is low and that you need to evaluate and improve the processes to encourage frequent releases.

      Choreo also displays the total number of deployments for the selected time range and the percentage increase or decrease compared to the previous time range.

      "},{"location":"monitoring-and-insights/delivery-insights/view-dora-metrics/#time-series-view_1","title":"Time series view","text":"

      The time series view for the Deployment Frequency metric visualizes the deployment count as a bar chart for the selected time period. Deployment count is aggregated based on the \u2018view by\u2019 selector. Hovering over each bar shows the counts for the aggregated period. Using this chart, organizations can identify deployment patterns, such as days of the week/months of the year where more deployments are likely to happen (near quarterly release days) and periods with fewer deployments. Decision-makers can then take steps to investigate and improve performance. This chart displays the pattern before and after a process change so you can use it to evaluate the team's performance after a significant process change.

      "},{"location":"monitoring-and-insights/delivery-insights/view-dora-metrics/#lead-time-for-change","title":"Lead Time for Change","text":"

      DORA team definition: The time it takes for a commit to reach production.

      In Choreo, this translates into the time between committing and promoting a deployment to production. Although this approach may overlook any commits you push to production between two commits, it effectively assesses the efficiency of the review, approval, and CI/CD processes. Therefore, focusing on the production commits is adequate. If a team commits locally for extended periods without deploying to production, this gets reflected in the Deployment Frequency charts.

      "},{"location":"monitoring-and-insights/delivery-insights/view-dora-metrics/#snapshot-view_2","title":"Snapshot view","text":"

      The snapshot view of this metric displays the 95th percentile of the lead time for the selected time period. 95th percentile serves as a better representation as it filters out large outliers that can taint the average value. Lower lead times for change suggest that your organization has efficient processes for change review, approval, and CI/CD, while longer times suggest that the process needs to improve. Organizations can also use the categorization label to determine their standpoint on global standards.

      Additionally, Choreo also displays the percentage increase or decrease compared to the last time period.

      "},{"location":"monitoring-and-insights/delivery-insights/view-dora-metrics/#time-series-view_2","title":"Time series view","text":"

      The time series view of this metric visualizes the lead time as a bar chart for the selected time period. The time is summed based on the \u2018view by\u2019 selector. To handle outliers, the y-axis employs a log scale that represents values read dynamically. Hovering over each bar displays the actual counts for the aggregated period. Using this chart, organizations can identify trends in their release process. For example, organizations can identify the time of the year when lead time rises, such as summer break. Also, organizations can use this to benchmark and evaluate new process changes. For example, if you introduced a process to include peer programming and reviewing, this chart can be used to evaluate its effect on the lead time and provide leadership with factual information to proceed further.

      "},{"location":"monitoring-and-insights/delivery-insights/view-dora-metrics/#change-failure-rate","title":"Change failure rate","text":"

      The DORA team definition: The percentage of deployments causing a failure in production.

      In Choreo, this translates to the ratio of deployments causing production failures to the total number of deployments. If there is at least one incident reported against a deployment, Choreo considers that deployment as a failed deployment in production. Any deployment-time failures are not counted as production failures because such failures don't impact the end user. For this metric to be accurate, the organization is expected to open incidents adhering to the proper format as it is crucial for Choreo to identify production failures.

      "},{"location":"monitoring-and-insights/delivery-insights/view-dora-metrics/#snapshot-view_3","title":"Snapshot view","text":"

      The snapshot view of this metric visualizes the change failure rate as a percentage for the selected time period. This will be the absolute percentage for the entire time period. When deciding on the time, the time of deployment is considered instead of the incident reported time. For example, the change failure rate for January 2023 will reflect the following: - All deployments that happened within January. - Any incidents that were reported at any time (in or after January) against the January deployments.

      This view helps leadership assess the quality of deliverables and identify areas for improvement. Higher rates suggest that the organization needs to improve its processes to bring in more quality assurance aspects such as improved code coverage and end-to-end test coverage.

      Additionally, Choreo also shows the percentage increase or decrease compared to the previous time period.

      "},{"location":"monitoring-and-insights/delivery-insights/view-dora-metrics/#time-series-view_3","title":"Time series view","text":"

      The time series view of this metric displays it as a line chart with data points corresponding to the granularity selected by the \u2018view by\u2019 selector. The absolute percentage is shown for each granularity. Hovering over the line chart displays the actual counts for the aggregated period. This chart helps leadership identify timely trends in product quality aspects. For example, this view displays the months of the year where the failure rate is high (for example, close to quarterly release/announcement dates). Also, you can use this to measure the effectiveness of changes introduced to improve quality. For example, if the organization introduced an end-to-end test pipeline integration to the PR approval process, they can use this view to factually observe the timely impact of that change and determine how it decreases the failure rate.

      "},{"location":"monitoring-and-insights/delivery-insights/view-dora-metrics/#mean-time-to-recovermttr","title":"Mean Time to Recover(MTTR)","text":"

      The DORA team definition: The time it takes for an organization to recover from a production failure.

      In Choreo, this measures the time from identifying a production incident to resolving it. This metric reflects the responsiveness and agility of incident management teams.

      Choreo depends on the open and close times of incidents to gather the relevant information. Therefore, for the dashboards to be accurate, organizations must follow process guidelines to update and close incident tickets efficiently in their incident management system.

      "},{"location":"monitoring-and-insights/delivery-insights/view-dora-metrics/#snapshot-view_4","title":"Snapshot view","text":"

      The snapshot view for this metric displays the mean recovery time for the selected time period. Choreo dynamically adjusts the time unit to measure this metric for better readability. This chart helps organizations evaluate the response time and agility of their incident handling teams, which in turn is an indication of stability. Higher MTTR means the leadership should look at new ways of improving the efficiency and agility of the teams handling incidents.

      "},{"location":"monitoring-and-insights/delivery-insights/view-dora-metrics/#time-series-view_4","title":"Time series view","text":"

      The time series view of this metric shows how the mean time to recovery changes over time on a granularity based on the \u2018view by\u2019 selector. Each time the granularity mean would be used as the aggregation factor. Hovering over the line chart displays the actual counts for the aggregated period. This view helps leadership understand timely trends on mean time to recovery, such as higher values during holiday periods when there is less staff. Also, you can use this measurement to evaluate the effectiveness of process changes such as introducing an incident response plan. The trend view clearly shows the before and after statistics and the effectiveness of the process change.

      "},{"location":"monitoring-and-insights/logs/view-pdp-logs/","title":"View Private Data Plane (PDP) Logs","text":"

      Choreo offers the capability to access runtime logs through its console. However, in cases where viewing logs for your PDP is not supported by Choreo yet, you can still view the runtime logs of your components via the log analyzing solution provided by your cloud vendor as a workaround.

      "},{"location":"monitoring-and-insights/logs/view-pdp-logs/#prerequisites","title":"Prerequisites","text":"

      Before you try out this guide, complete the following:

      1. Go to https://console.choreo.dev/, and sign in using your preferred method.
      2. Select your component from Components Listing. This will open the Overview page of your component.
      3. In the left navigation menu, click Runtime under DevOps.
      4. Copy the Release ID and the Namespace. Save it for later.
      "},{"location":"monitoring-and-insights/logs/view-pdp-logs/#view-private-data-plane-pdp-logs-with-azure-log-analytics","title":"View Private Data Plane (PDP) logs with Azure Log Analytics","text":"

      You can view your PDP logs with Azure Log Analytics by following the steps below:

      1. Go to https://portal.azure.com/.
      2. Follow the Azure Log Analytics Tutorial and open log analytics of your relative log analytics workspace.
      3. Copy and paste the query below into the query editor.
      4. Replace the <START_TIME_STAMP EX: 2023-04-10T07:07:31.684Z> and <END_TIME_STAMP EX: 2023-04-21T07:27:31.684Z> values as required. Replace the '' and '' with the values you copied by following the steps in the prerequisites section. Replace the <OPTIONAL SEARCH PHRASE> with your search term, or leave it blank if you don't require any search filtering.
      5. Run the query to extract the relevant logs.
        6. let startDateTime = datetime('<START_TIME_STAMP EX: 2023-04-10T07:07:31.684Z>');\nlet endDateTime = datetime('<END_TIME_STAMP EX: 2023-04-21T07:27:31.684Z>');\nlet releaseId = '<RELEASE_ID>';\nlet namespace = '<NAMESPACE>';\nlet searchPhrase = '<OPTIONAL SEARCH PHRASE>';\nlet startDateTimeKPI = iff(datetime_diff('second', endDateTime, startDateTime) > 60, startDateTime, endDateTime - 2m);let endDateTimeKPI = iff(datetime_diff('second', endDateTime, startDateTime) > 60, endDateTime, startDateTime + 2m);let filteredLogLevels = dynamic([]);\nlet hasNoLevelFilter = array_length(filteredLogLevels) == 0;\nlet commonKeys = dynamic(['time', 'level', 'module', 'traceId', 'spanId', 'message']);\nlet ContainerIdList = KubePodInventory\n| where TimeGenerated > startDateTimeKPI and TimeGenerated < endDateTimeKPI\n| where Namespace == namespace\n| where extractjson('$.[0].release_id', PodLabel) == releaseId\n| distinct ContainerID;\nlet data = ContainerLog\n| where TimeGenerated > startDateTime and TimeGenerated < endDateTime\n| where ContainerID in (ContainerIdList)\n| where searchPhrase == \"\" or LogEntry contains searchPhrase\n| top 126 by TimeGenerated desc\n| extend logs = parse_json(LogEntry)\n| project TimeGenerated, LogLevel = iif(isempty(logs['level']), iff(LogEntrySource == 'stderr', 'ERROR', 'INFO'), logs['level']), LogEntry = iif(isempty(logs['message']), logs, logs['message']),\nKeyValuePair = bag_remove_keys(logs, commonKeys)\n| where hasNoLevelFilter or LogLevel in (filteredLogLevels);\nlet lastTimeStamp = data | top 1 by TimeGenerated asc | project TimeGenerated;\nlet trimmedData = data | where TimeGenerated > toscalar(lastTimeStamp)| sort by TimeGenerated desc;\nlet selected = iff(toscalar(data | count) == 126, 'trimmedData', 'data');\nlet choose = (selector:string){   union   (trimmedData | where selector == 'trimmedData'),    (data | where selector == 'data')};\nchoose(selected);\n
        "},{"location":"monitoring-and-insights/logs/view-pdp-logs/#view-private-data-plane-pdp-logs-with-amazon-cloudwatch","title":"View Private Data Plane (PDP) logs with Amazon CloudWatch","text":"
        1. Go to https://portal.azure.com/.
        2. Follow the AWS Analyzing Log Data documentation and open Log Insights.
        3. Select the relevant region and the relevant log group (the log group string has the cluster name and \u201c/application\u201d appended at the end).
        4. Select the required time range.
        5. Copy the query below and paste it into the query editor.
        6. Replace the <RELEASE_ID> with the values you copied by following the steps in the prerequisites section. Replace the <OPTIONAL SEARCH PHRASE> with your search term, or leave it blank if you don't require any search filtering.
        7. Run the query to extract the logs.
        fields @timestamp, @message\n| filter kubernetes.labels.release_id == \"<RELEASE_ID>\"\n| filter @message like \"<OPTIONAL SEARCH PHRASE>\"\n
        "},{"location":"monitoring-and-insights/work-with-choreo-insights-api/access-the-choreo-insights-api/","title":"Access the Choreo Insights API","text":"

        The Usage Insights page in the Choreo Console displays data retrieved from the Insights API exposed over the Internet. However, in some scenarios, you may need to retrieve data from external systems and implement custom dashboards to display the data.

        Choreo provides a secure and user-friendly approach to accomplish this requirement. Follow the steps given below:

        "},{"location":"monitoring-and-insights/work-with-choreo-insights-api/access-the-choreo-insights-api/#become-a-member-of-the-choreo-system-organization","title":"Become a member of the Choreo System organization","text":"

        1. Access the Developer Portal of the Choreo System organization via https://devportal.choreo.dev/choreosystem/applications and sign in using your preferred method.

        2. To obtain access to the Choreo System organization, click Request Access.

        "},{"location":"monitoring-and-insights/work-with-choreo-insights-api/access-the-choreo-insights-api/#create-an-application-and-generate-keys","title":"Create an application and generate keys","text":"

        To create an application and generate keys, follow the steps below:

        1. To create a new application in the Choreo System organization, click + Create Application.

        2. Enter a name for the application and click Create. This creates the application and takes you to the Overview page.

        3. To subscribe to the Insights API via the newly created application, follow the steps below:

          1. In the left navigation menu, click Subscriptions.
          2. In the Subscription Management pane, click + Add APIs.
          3. Search for Insights and click Add.

        4. To generate credentials for the application, follow the steps given below:

          1. In the left navigation menu, click Production under Credentials.
          2. Click Generate Credentials. Choreo generates tokens and populates the Consumer Key and Consumer Secret fields in the Application Keys pane.

        5. To specify an appropriate token expiry time for the application, follow the steps given below:

          1. In the Application Keys pane, click to expand Advanced Configurations.

          2. Specify an appropriate value in the Application access token expiry time field and click Update.

        6. Execute the following cURL command to generate an access token:

          curl --location --request POST 'https://sts.choreo.dev/oauth2/token' \\\n--header 'Authorization: Basic <BASE64_ENCODED_CONSUMER_KEY_AND_CONSUMER_SECRET_OF_YOUR_APP_HERE>' \\\n--header 'Content-Type: application/x-www-form-urlencoded' \\\n--data-urlencode 'grant_type=client_credentials' \\\n--data-urlencode 'orgHandle=<YOUR_ORG_HANDLE_HERE>' \\\n--data-urlencode 'scope=apim:api_manage'\n

          Info

          To obtain your organization handle, follow the steps given below:

          1. Go to https://console.choreo.dev and sign in using your preferred method.
          2. In the Choreo Console, click your username in the top right corner.
          3. In the drop-down menu, click\u00a0Settings.
          4. In\u00a0the\u00a0Organization\u00a0pane, click Copy Handle.

          You can use the generated token to access the Insights API exposed via https://choreocontrolplane.choreo.dev/93tu/insights/1.0.0/query-api.

          The following is a sample cURL command to invoke the Insights API:

          curl --location --request POST 'https://choreocontrolplane.choreo.dev/93tu/insights/1.0.0/query-api' \\\n--header 'Content-Type: application/json' \\\n--header 'Authorization: Bearer <TOKEN_HERE>' \\\n--data-raw '{\"query\":\"query ($org: OrgFilter!) {listEnvironments(org: $org){id\\n name}}\",\"variables\":{\"org\":{\"orgId\":\"<ORG_UUID_HERE>\"}}}'\n

          Tip

          • When the token expires, you can generate a new token programmatically by making an API call to the token endpoint using the client credentials grant type.
          • If a token theft occurs, you can revoke the token by making an API call to the revoke endpoint.

        "},{"location":"monitoring-and-insights/work-with-choreo-insights-api/choreo-insights-api/","title":"Choreo Insights API","text":"

        The Choreo Insights API is a GraphQL API that allows you to retrieve data from external systems based on specific criteria. This guide describes the operations and schema-defined types you can use to retrieve data via the Choreo Insights API.

        • Allowed operations: Queries
        • Schema-defined types: Objects, Inputs, Enums, and Scalars
        "},{"location":"monitoring-and-insights/work-with-choreo-insights-api/choreo-insights-api/#try-out","title":"Try out","text":"

        You can try out the Choreo Insights API with your data via GraphQL Explorer.

        Warning

        The GraphQL Explorer is currently not compatible with the Safari web browser due to a known issue.

        "},{"location":"monitoring-and-insights/work-with-choreo-insights-api/choreo-insights-api/#query","title":"Query","text":"

        The query root of the Choreo Insights GraphQL API.

        Field Argument Type Description listAllAPI [API] Fetches all the APIs with the given combination of tenant ID, environment ID, and organization ID. Optionally, you can configure the provider parameter to further filter the APIs by a specific provider. provider String The name of the API provider. dataFilter DataFilter! The data filter. listApplications [Application] Fetches all the applications with the given combination of tenant ID, environment ID, and organization ID. Optionally, you can configure the applicationFilter parameter to further filter the applications by a specific application filter. applicationFilter ApplicationFilter The application filter. dataFilter DataFilter! The data filter. listProviders [Provider] Fetches all the API providers with the given combination of tenant ID, environment ID, and organization ID. dataFilter DataFilter! The data filter. listSubscribers [Subscriber] Fetches all the API subscribers with the given combination of tenant ID, environment ID, and organization ID. Optionally, you can configure the subscriberFilter parameter to further filter the subscribers. subscriberFilter SubscriberFilter The subscriber filter. dataFilter DataFilter! The data filter. listOrganizations [Organization] Fetches all the organizations of a user. listEnvironments [Environment] Fetches all the environments of an organization. org OrgFilter! The organization filter. projectId String The project ID by which the results need to be filtered. It is optional to specify a value for this parameter. Note that providing a project ID with an on-prem key is not allowed. listTenants [String] Fetches all the tenants with the given combination of environment ID and organization ID. tenantDataFilter TenantDataFilter! The tenant filter. getTotalTraffic Int Returns the total traffic during the given time range for the specified combination of tenant ID, environment ID, and organization ID. filter TimeFilter! The time filter. dataFilter DataFilter! The data filter. getTotalErrors Int Returns the total number of errors that occurred during the given time range for the specified combination of tenant ID, environment ID, and organization ID. filter TimeFilter! The time filter. dataFilter DataFilter! The data filter. getOverallLatency Float Returns the overall response latency (95th percentile value) during the given time range for the specified combination of tenant ID, environment ID, and organization ID. filter TimeFilter! The time filter. dataFilter DataFilter! The data filter. getLatencySummary LatencySummary Returns the response latency value (95th percentile value) for each time granularity within the specified time range for the given combination of tenant ID, environment ID, and organization ID. Optionally, you can configure the latencySummaryFilter parameter to further filter the results. filter TimeFilter! The time filter. latencySummaryFilter LatencySummaryFilter The latency summary filter. dataFilter DataFilter! The data filter. getSuccessSummary SuccessSummary Returns the number of successful (2xx response code) hit count for each time granularity within the specified time range for the given combination of tenant ID, environment ID, and organization ID. Optionally, you can configure the granularity parameter to override the default granularity value. filter TimeFilter! The time filter. dataFilter DataFilter! The data filter. granularity String The granularity value. getErrorSummary ErrorSummary Returns the number of unsuccessful hits (i.e., the total of both 4xx and 5xx response codes) for each time granularity within the specified time range for the given combination of tenant ID, environment ID, and organization ID. Optionally, you can configure the granularity parameter to override the default granularity value. filter TimeFilter! The time filter. dataFilter DataFilter! The data filter. granularity String The granularity value. getErrorsByCategory ErrorsByCategory Returns the number of proxy errors (i.e., the total of both 4xx and 5xx response codes) by each error category for each time granularity within the specified time range for the given combination of tenant ID, environment ID, and organization ID. Optionally, you can configure the errorsByCategoryFilter parameter to further filter the results. timeFilter TimeFilter! The time filter. errorsByCategoryFilter ErrorsByCategoryFilter The errors by category filter. dataFilter DataFilter! The data filter. getErrorsDetails DetailsOfErrors Returns details of each proxy error (for both 4xx and 5xx response codes) within the specified time range for the given combination of tenant ID, environment ID, and organization ID. Optionally, you can configure the errorsDetailsFilter parameter to further filter the results. timeFilter TimeFilter! The time filter. errorsDetailsFilter ErrorsDetailsFilter The error details filter. dataFilter DataFilter! The data filter. getProxyTargetErrorsOverTime [ErrorsByStatusCodeCategory] Returns a list of hit counts for proxy and target errors for each time granularity within the specified time range for the given combination of tenant ID, environment ID, and organization ID. The errors in each proxy and target result set are grouped as 4xx, 5xx, and total. Optionally, you can configure the errorsByStatusCodeFilter parameter to further filter the results. timeFilter TimeFilter! The time filter. errorsByStatusCodeFilter ErrorsByStatusCodeFilter The errors by status code filter. dataFilter DataFilter! The data filter. getErrorsByStatusCode ErrorsByStatusCode Returns the hit count for each error response code (401, 404, and 500 etc.,) for each API within the specified time range for the given combination of tenant ID, environment ID, and organization ID. timeFilter TimeFilter! The time filter. errorCountByStatusCodeFilter ErrorCountByStatusCodeFilter! The error count by status code filter. dataFilter DataFilter! The data filter. getTotalErrorsByAPI TotalError Returns the total proxy error hit count for an API across for the given combination of tenant ID, environment ID, and organization ID. Optionally, you can configure the filter parameter to further filter the results by a given time range. filter TimeFilter The time filter. dataFilter DataFilter! The data filter. apiId ID! The API ID. getAPIUsageOverTime [APIUsageOverTime] Returns a list of details related to the usage of each API over time for each time granularity within the specified time range for the given combination of tenant ID, environment ID, and organization ID. Optionally, you can configure the apiUsageOvertimeFilter parameter to further filter the results. timeFilter TimeFilter! The time filter. apiUsageOvertimeFilter APIUsageOverTimeFilter The API usage overtime filter. dataFilter DataFilter! The data filter. getAPIUsageByAppOverTime APIUsageByAppOverTime Returns API usage by each application over time for each time granularity within the specified time range for the given combination of tenant ID, environment ID, and organization ID. Optionally, you can configure the apiUsageOvertimeFilter parameter to further filter the results. timeFilter TimeFilter! The time filter. apiUsageOvertimeFilter APIUsageOverTimeFilter The API usage overtime filter. dataFilter DataFilter! The data filter. getAPIUsageByBackendOverTime APIUsageByBackendOverTime Returns API usage by each backend over time for each time granularity within the specified time range for the given combination of tenant ID, environment ID, and organization ID. Optionally, you can configure the apiUsageByBackendOverTimeFilter parameter to further filter the results. timeFilter TimeFilter! The time filter. apiUsageByBackendOverTimeFilter APIUsageByBackendOverTimeFilter The API usage by backend overtime filter. dataFilter DataFilter! The data filter. getResourceUsage ResourceUsages Returns API usage by resource within the specified time range for the given combination of tenant ID, environment ID, and organization ID. Optionally, you can configure the resourceUsageFilter parameter to further filter the results. timeFilter TimeFilter! The time filter. resourceUsageFilter ResourceUsageFilter The resource usage filter. dataFilter DataFilter! The data filter. getTotalTrafficByAPI Int Returns the total hit count for an API for the given combination of tenant ID, environment ID, and organization ID. Optionally, you can configure the filter parameter to further filter the results by a given time range. filter TimeFilter The time filter. dataFilter DataFilter! The data filter. apiId ID! The API ID. topSlowestAPIs [SlowAPI] Returns a list of top slowest APIs based on the response latency (95th percentile value) within the specified time range for the given combination of tenant ID, environment ID, and organization ID. filter TimeFilter! The time filter. dataFilter DataFilter! The data filter. limit Int! The limit for the slow APIs list. getLatency APILatency Returns different latency category values (95th percentile values) for a given API over time for each time granularity within the specified time range for the given combination of tenant ID, environment ID, and organization ID. timeFilter TimeFilter! The time filter. latencyFilter LatencyFilter! The latency filter. dataFilter DataFilter! The data filter. getOverallLatencyByAPI OverallLatency Returns the overall response latency (95th percentile value) for an API for the given combination of tenant ID, environment ID, and organization ID. Optionally, you can configure the filter parameter to further filter the results by a given time range. filter TimeFilter The time filter. dataFilter DataFilter! The data filter. apiId ID! The API ID. getCacheHitsAndMisses CacheHits Return the total number of response cache hits, misses, and hit percentage for an API over time for each time granularity within the specified time range for the given combination of tenant ID, environment ID, and organization ID. timeFilter TimeFilter! The time filter. cacheFilter CacheFilter The cache filter. dataFilter DataFilter! The data filter. getTopPlatforms [Platform] Returns a list of top platforms ranked based on the hit count within the specified time range for the given combination of tenant ID, environment ID, and organization ID. The result list includes the top nine platforms with the respective hit count, and all the rest of the platforms are labeled as **Other** with the cumulated hit count. Optionally, you can configure the deviceFilter parameter to further filter the results. timeFilter TimeFilter! The time filter. deviceFilter DeviceFilter The device filter. dataFilter DataFilter! The data filter. getTopUserAgents [UserAgent] Returns a list of top user agents ranked based on the hit count within the specified time range for the given combination of tenant ID, environment ID, and organization ID. The result list includes the top nine user agents with the respective hit count, and all the rest of the platforms are labeled as **Other** with the cumulated hit count. Optionally, you can configure the deviceFilter parameter to further filter the results. timeFilter TimeFilter! The time filter. deviceFilter DeviceFilter The device filter. dataFilter DataFilter! The data filter. getAPIUsageByGeoLocation [UsageByGeoLocation] NOTE: Currently, this operation returns data only for on-premise environments. Returns API usage by country within the specified time range for the given combination of tenant ID, environment ID, and organization ID. Optionally, you can configure the geoLocationFilter parameter to further filter the results. timeFilter TimeFilter! The time filter. geoLocationFilter GeoLocationFilter The geolocation filter. dataFilter DataFilter! The data filter. getAPIsUsageByApplications [APIUsageByApplication] Returns details relating to the usage of each API by application within the specified time range for the given combination of tenant ID, environment ID, and organization ID. Optionally, you can configure the apiUsageByAppFilter parameter to further filter the results. timeFilter TimeFilter! The time filter. apiUsageByAppFilter APIUsageByAppFilter The API usage by app filter. dataFilter DataFilter! The data filter. getTopAPIsByAlertCount TopAPIsByAlertCount Returns top APIs ranked based on the alert count within the specified time range for the given combination of tenant ID, environment ID, and organization ID. Optionally, you can configure the topAPIsByAlertCountFilter parameter to further filter the results. timeFilter TimeFilter! The time filter. topAPIsByAlertCountFilter TopAPIsByAlertCountFilter The top APIs by alert count filter. dataFilter DataFilter! The data filter. getAlertSummary AlertSummaries Returns a summary for each alert within the specified time range for the given combination of tenant ID, environment ID, and organization ID. Optionally, you can configure the alertSummaryFilter parameter to further filter the results. timeFilter TimeFilter! The time filter. alertSummaryFilter AlertSummaryFilter The alert summary filter. dataFilter DataFilter! The data filter. getSuccessAPIsUsageByApplications [SuccessAPIUsageByApplication] NOTE: This operation can only be invoked via using an on-prem key as the authentication header. Returns a list of successful hit counts (i.e., 2xx response codes) within the specified time range for each API, grouped by each application. Optionally, you can configure the successAPIUsageByAppFilter parameter to further filter the results. timeFilter TimeFilter! The time filter. successAPIUsageByAppFilter SuccessAPIUsageByAppFilter The successful API usage by application filter. getSuccessAPIsUsageByApplicationsWithOnPremKey [SuccessAPIUsageByApplication] Returns a list of successful hit counts (i.e., 2xx response codes) within the specified time range for each API, grouped by each application. Optionally, you can configure the successAPIUsageByAppFilter parameter to further filter the results. onPremKey String! The value of the On-Prem key. timeFilter TimeFilter! The time filter. successAPIUsageByAppFilter SuccessAPIUsageByAppFilter The successful API usage by application filter. getCustomReportOvertime CustomReportOvertime Returns the summary of hits or latency data as specified for the selected time duration, grouped by time spans. dataFilter DataFilter! The data filter. timeFilter TimeFilter! The time filter. metric Metric! The metric for which data needs to be retrieved. groupByFields [GroupByField]! The column/field by which data needs to be retrieved. groupByValues [String]! The value used to filter by the groupByField. granularity String! The granularity value for which data is retrieved. getCustomReportTopOvertime CustomReportTopOvertime Returns the summary of hits or latency data as specified for the selected time duration, grouped by time spans for the top N values for the selected groupByField. dataFilter DataFilter! The data filter. timeFilter TimeFilter! The time filter. metric Metric! The metric for which data needs to be retrieved. groupByFields [GroupByField]! The column/field by which the data should be grouped. groupByValues [String]! The value used to filter by the groupByField. granularity String! The granularity value for which data is retrieved. getGroupByValues [[String]] Returns a list of value sets by which you can group the data available for the selected groupBy fields. dataFilter DataFilter! The data filter. groupByFields [GroupByField]! The column/field for which the API needs to retrieve distinct values. groupByValues [String]! The value used to filter by the groupByField."},{"location":"monitoring-and-insights/work-with-choreo-insights-api/choreo-insights-api/#objects","title":"Objects","text":""},{"location":"monitoring-and-insights/work-with-choreo-insights-api/choreo-insights-api/#api","title":"API","text":"

        Represents API details.

        Field Argument Type Description id ID! The ID of the API. name String! The API name. version String! The API version. provider String! The API provider name."},{"location":"monitoring-and-insights/work-with-choreo-insights-api/choreo-insights-api/#apilatency","title":"APILatency","text":"

        Represents latency values for a single API over time.

        Field Argument Type Description summary [Latency] A list containing latency category values over time. Returns an empty array if no data is available. granularity String! The granularity value for which data is retrieved."},{"location":"monitoring-and-insights/work-with-choreo-insights-api/choreo-insights-api/#apiusage","title":"APIUsage","text":"

        Represents the API usage for a single timestamp. The timestamp is calculated based on the granularity value provided.

        Field Argument Type Description timeSpan String! Represents a timestamp value that is calculated based on the specified granularity value. For example, if the granularity value is 1d, the timestamp represents the start of the day calculated adhering to the timezone provided in the time filter. e.g., timeSpan: '2021-06-21T00:00:00.0000000+05:30' count Int! The API usage count."},{"location":"monitoring-and-insights/work-with-choreo-insights-api/choreo-insights-api/#apiusagebyapp","title":"APIUsageByApp","text":"

        Represents API usage across APIs by a single application.

        Field Argument Type Description applicationId ID! The application ID. applicationName String! The application name. applicationOwner String! The name of the application owner. usage [APIUsage] A list containing the APIs usage values. Returns an empty array if no data is available."},{"location":"monitoring-and-insights/work-with-choreo-insights-api/choreo-insights-api/#apiusagebyappovertime","title":"APIUsageByAppOverTime","text":"

        Represents API usage across APIs by applications over time.

        Field Argument Type Description usage [APIUsageByApp] A list containing the API usage values across APIs, grouped by the application. Returns an empty array if no data is available. granularity String! The granularity value for which data is retrieved."},{"location":"monitoring-and-insights/work-with-choreo-insights-api/choreo-insights-api/#apiusagebyapplication","title":"APIUsageByApplication","text":"

        Represents a single API usage by a single application.

        Field Argument Type Description apiId String! The ID of the API. applicationId String! The Application ID. applicationName String! The application name. applicationOwner String! The name of the application owner. count Int! The usage of the API by the application."},{"location":"monitoring-and-insights/work-with-choreo-insights-api/choreo-insights-api/#apiusagebybackend","title":"APIUsageByBackend","text":"

        Represents API usage across APIs by a single backend.

        Field Argument Type Description backend String! The name of the backend. usage [APIUsage] A list containing the APIs usage values. Returns an empty array if no data is available."},{"location":"monitoring-and-insights/work-with-choreo-insights-api/choreo-insights-api/#apiusagebybackendovertime","title":"APIUsageByBackendOverTime","text":"

        Represents API usage across APIs by each backend over time.

        Field Argument Type Description usage [APIUsageByBackend] A list containing the API usage values across APIs by each backend. Returns an empty array if no data is available. granularity String! The granularity value for which data is retrieved."},{"location":"monitoring-and-insights/work-with-choreo-insights-api/choreo-insights-api/#apiusageovertime","title":"APIUsageOverTime","text":"

        Represents a single API usage over time.

        Field Argument Type Description apiId ID The ID of the API. usage [APIUsage] A list containing the API usage values. Returns an empty array if no data is available. granularity String! The granularity value for which data is retrieved."},{"location":"monitoring-and-insights/work-with-choreo-insights-api/choreo-insights-api/#alertsummaries","title":"AlertSummaries","text":"

        Represents alert summaries.

        Field Argument Type Description usage [AlertSummary] A list containing the alert summary for each alert. Returns an empty array if no data is available. pagination Pagination! The pagination details."},{"location":"monitoring-and-insights/work-with-choreo-insights-api/choreo-insights-api/#alertsummary","title":"AlertSummary","text":"

        Represents a summary for an alert.

        Field Argument Type Description apiId ID! The ID of the API. timestamp String! Represents a timestamp value that is calculated based on the specified granularity value. For example, if the granularity value is 1d, the timestamp represents the start of the day calculated adhering to the timezone provided in the time filter. e.g., timeSpan: '2021-06-21T00:00:00.0000000+05:30' category String! The alert category. Possible values are LATENCY and TRAFFIC. metric String! The alert metric. Possible values are RESPONSE_LATENCY and TOTAL_TRAFFIC. severity String! The severity level of the alert. Possible values are LOW, MEDIUM, and HIGH. message String! The alert details."},{"location":"monitoring-and-insights/work-with-choreo-insights-api/choreo-insights-api/#application","title":"Application","text":"

        Represents application details.

        Field Argument Type Description id ID! The Application ID. name String! The application name. owner String! The name of the application owner."},{"location":"monitoring-and-insights/work-with-choreo-insights-api/choreo-insights-api/#cachehit","title":"CacheHit","text":"

        Represents the response cache hits and misses for a single timestamp. The timestamp is calculated based on the granularity value provided.

        Field Argument Type Description timeSpan String! Represents a timestamp value that is calculated based on the specified granularity value. For example, if the granularity value is 1d, the timestamp represents the start of the day calculated adhering to the timezone provided in the time filter. e.g., timeSpan: '2021-06-21T00:00:00.0000000+05:30' hits Int! The number of times the response cache was hit. misses Int! The number of times the response cache was missed. hitPercentage Float! The response cache hits as a percentage of the sum of hits and misses."},{"location":"monitoring-and-insights/work-with-choreo-insights-api/choreo-insights-api/#cachehits","title":"CacheHits","text":"

        Represents the response cache hits and misses over time.

        Field Argument Type Description summary [CacheHit] A list containing cache hits, misses, and the hit percentage over time. Returns an empty array if no data is available. granularity String! The granularity value for which data is retrieved."},{"location":"monitoring-and-insights/work-with-choreo-insights-api/choreo-insights-api/#customreportgroupby","title":"CustomReportGroupBy","text":"

        Represents the usage data overtime for the selected parameters of a specific groupByValue.

        Field Argument Type Description groupByValue ID! The distinct group-by value that is used as an ID. usage [CustomReportUsage] A list containing the usage values. This returns an empty array if no data is available."},{"location":"monitoring-and-insights/work-with-choreo-insights-api/choreo-insights-api/#customreportovertime","title":"CustomReportOvertime","text":"

        Represents usage data overtime for the selected parameters.

        Field Argument Type Description usage [CustomReportUsage] A list containing the usage values. This returns an empty array if no data is available. granularity String! The granularity value for which data is retrieved."},{"location":"monitoring-and-insights/work-with-choreo-insights-api/choreo-insights-api/#customreporttopovertime","title":"CustomReportTopOvertime","text":"

        Represents usage data overtime for the selected parameters grouped by the top N groupByValues.

        Field Argument Type Description usage [CustomReportGroupBy] A list containing the usage values grouped by the selected groupByField. This returns an empty array if no data is available. granularity String! The granularity value for which data is retrieved."},{"location":"monitoring-and-insights/work-with-choreo-insights-api/choreo-insights-api/#customreportusage","title":"CustomReportUsage","text":"

        Represents usage data for a single timestamp in CustomReports.

        Field Argument Type Description timeSpan String! Represents a timestamp value that is calculated based on the specified granularity value. For example, if the granularity value is 1d, the timestamp represents the start of the day calculated adhering to the timezone provided in the time filter. e.g., timeSpan: '2021-06-21T00:00:00.0000000+05:30' value Int! The usage value (Hit Count/ Latency)."},{"location":"monitoring-and-insights/work-with-choreo-insights-api/choreo-insights-api/#detailsoferrors","title":"DetailsOfErrors","text":"

        Represents error details over time.

        Field Argument Type Description usage [ErrorDetails]! A list containing error details over time. Returns an empty array if no data is available. pagination Pagination! The pagination details."},{"location":"monitoring-and-insights/work-with-choreo-insights-api/choreo-insights-api/#environment","title":"Environment","text":"

        Represents an environment.

        Field Argument Type Description id String! The environment ID. externalEnvId String! The external environment ID. internalEnvId String The internal environment ID. sandboxEnvId String The sandbox environment ID. name String! The environment name. type EnvironmentType! The environment type. A Choreo environment is labeled as CHOREO, a private Choreo environment is labeled as CHOREO_PRIVATE, and the on-premise environment is labeled as ON_PREM."},{"location":"monitoring-and-insights/work-with-choreo-insights-api/choreo-insights-api/#errorcountbycategory","title":"ErrorCountByCategory","text":"

        Represents the number of errors from each category for a single timestamp. The timestamp is calculated according to the provided granularity value. If you select some categories, the error counts are retrieved only for those categories, and a null value is shown for the other categories that are not selected.

        Field Argument Type Description timeSpan String! Represents a timestamp value that is calculated based on the specified granularity value. For example, if the granularity value is 1d, the timestamp represents the start of the day calculated adhering to the timezone provided in the time filter. e.g., timeSpan: '2021-06-21T00:00:00.0000000+05:30' auth Int The count of authorization errors. targetConnectivity Int The count of target connectivity errors. throttled Int The count of throttling errors. other Int The count of other errors."},{"location":"monitoring-and-insights/work-with-choreo-insights-api/choreo-insights-api/#errorcountbycode","title":"ErrorCountByCode","text":"

        Represents the error count for a single error status code.

        Field Argument Type Description statusCode String! The error status code. count Int! The error count."},{"location":"monitoring-and-insights/work-with-choreo-insights-api/choreo-insights-api/#errorcountbycodeforapi","title":"ErrorCountByCodeForAPI","text":"

        Represents the error count for each status code for a single API.

        Field Argument Type Description apiId ID! The ID of the API. errorCountByCode [ErrorCountByCode] A list containing the error count for each error status code. Returns an empty array if no data is available."},{"location":"monitoring-and-insights/work-with-choreo-insights-api/choreo-insights-api/#errordetails","title":"ErrorDetails","text":"

        Represents details of an error for a single timestamp. The timestamp is calculated according to the granularity value provided.

        Field Argument Type Description apiId ID The ID of the API. timeSpan String! Represents a timestamp value that is calculated based on the specified granularity value. For example, if the granularity value is 1d, the timestamp represents the start of the day calculated adhering to the timezone provided in the time filter. e.g., timeSpan: '2021-06-21T00:00:00.0000000+05:30' applicationId String The Application ID. applicationName String The application name. applicationOwner String The name of the application owner. reason String! The reason for the error. count Int! The error count."},{"location":"monitoring-and-insights/work-with-choreo-insights-api/choreo-insights-api/#errorstatuscodecategorycounts","title":"ErrorStatusCodeCategoryCounts","text":"

        Represents errors by the main status code (4xx or 5xx) and the total error count.

        Field Argument Type Description _4xx Int The number of client errors. _5xx Int The number of server errors. total Int The total number of client and server errors."},{"location":"monitoring-and-insights/work-with-choreo-insights-api/choreo-insights-api/#errorsummary","title":"ErrorSummary","text":"

        Provides the unsuccessful usage (i.e., 4xx and 5xx response codes) summary across all APIs.

        Field Argument Type Description summary [ErrorValue]! A list containing unsuccessful usage values. Returns an empty array if no data is available. granularity String! The granularity value for which data is retrieved."},{"location":"monitoring-and-insights/work-with-choreo-insights-api/choreo-insights-api/#errorvalue","title":"ErrorValue","text":"

        Represents the unsuccessful request count (i.e., 4xx and 5xx response codes) for a single timestamp. The timestamp is calculated based on the granularity value provided.

        Field Argument Type Description timeSpan String Represents a timestamp value that is calculated based on the specified granularity value. For example, if the granularity value is 1d, the timestamp represents the start of the day calculated adhering to the timezone provided in the time filter. e.g., timeSpan: '2021-06-21T00:00:00.0000000+05:30' errorCount Int Represents the error request count."},{"location":"monitoring-and-insights/work-with-choreo-insights-api/choreo-insights-api/#errorsbycategory","title":"ErrorsByCategory","text":"

        Represents the errors by category over time.

        Field Argument Type Description errors [ErrorCountByCategory] A list containing the error count for each error category over time. Returns an empty array if no data is available. granularity String! The granularity value for which data is retrieved."},{"location":"monitoring-and-insights/work-with-choreo-insights-api/choreo-insights-api/#errorsbystatuscode","title":"ErrorsByStatusCode","text":"

        Represents the error counts grouped by status code for each API.

        Field Argument Type Description errors [ErrorCountByCodeForAPI]! A list containing the error count for each status code for each API. Returns an empty array if no data is available. pagination Pagination! Pagination details."},{"location":"monitoring-and-insights/work-with-choreo-insights-api/choreo-insights-api/#errorsbystatuscodecategory","title":"ErrorsByStatusCodeCategory","text":"

        Represents the error category values (grouped as 4xx, 5xx, and total) for both proxy and target errors for a single timestamp. The timestamp is calculated based on the granularity value provided.

        Field Argument Type Description timeSpan String! Represents a timestamp value that is calculated based on the specified granularity value. For example, if the granularity value is 1d, the timestamp represents the start of the day calculated adhering to the timezone provided in the time filter. e.g., timeSpan: '2021-06-21T00:00:00.0000000+05:30' proxy ErrorStatusCodeCategoryCounts Represents proxy-related errors categorized as client errors (4xx response codes) or server errors (5xx response codes), and the total of both categories. target ErrorStatusCodeCategoryCounts Represents target-related errors categorized as client errors (4xx response codes) or server errors (5xx response codes), and the total of both categories."},{"location":"monitoring-and-insights/work-with-choreo-insights-api/choreo-insights-api/#latency","title":"Latency","text":"

        Represents latency values for each latency category for a single timestamp. The timestamp is calculated based on the granularity value provided.

        Field Argument Type Description timeSpan String Represents a timestamp value that is calculated based on the specified granularity value. For example, if the granularity value is 1d, the timestamp represents the start of the day calculated adhering to the timezone provided in the time filter. e.g., timeSpan: '2021-06-21T00:00:00.0000000+05:30' response Int The response latency (95th percentile) in milliseconds (ms). backend Int The backend latency (95th percentile) in milliseconds (ms). requestMediation Int The request mediation latency (95th percentile) in milliseconds (ms). responseMediation Int The response mediation latency (95th percentile) in milliseconds (ms). responseMedian Int The median (50th percentile) of the response latency in milliseconds (ms). backendMedian Int The median (50th percentile) of the backend latency in milliseconds (ms). requestMediationMedian Int The median (50th percentile) of the request mediation latency in milliseconds (ms). responseMediationMedian Int The median (50th percentile) of the response mediation latency in milliseconds (ms)."},{"location":"monitoring-and-insights/work-with-choreo-insights-api/choreo-insights-api/#latencysummary","title":"LatencySummary","text":"

        Provides the latency summary.

        Field Argument Type Description summary [LatencyValue]! A list containing latency values. Returns an empty array if no data is available. granularity String! The granularity value for which data is retrieved."},{"location":"monitoring-and-insights/work-with-choreo-insights-api/choreo-insights-api/#latencyvalue","title":"LatencyValue","text":"

        Represents the latency value for a single timestamp. The timestamp is calculated according to the provided granularity value.

        Field Argument Type Description timeSpan String! Represents a timestamp value that is calculated based on the specified granularity value. For example, if the granularity value is 1d, the timestamp represents the start of the day calculated adhering to the timezone provided in the time filter. e.g., timeSpan: '2021-06-21T00:00:00.0000000+05:30' latencyTime Float! Represents the latency (95th percentile) time in milliseconds (ms)."},{"location":"monitoring-and-insights/work-with-choreo-insights-api/choreo-insights-api/#organization","title":"Organization","text":"

        Represents an organization.

        Field Argument Type Description id String! The organization ID. uuid ID! The organization UUID. handle String! The organization handle name. name String! The organization name."},{"location":"monitoring-and-insights/work-with-choreo-insights-api/choreo-insights-api/#overalllatency","title":"OverallLatency","text":"

        Represents the overall latency values.

        Field Argument Type Description response Float The response latency (95th percentile value) in milliseconds (ms)."},{"location":"monitoring-and-insights/work-with-choreo-insights-api/choreo-insights-api/#pagination","title":"Pagination","text":"

        Represents pagination details.

        Field Argument Type Description total Int! The total number of results. limit Int! The number of items in the result set. offset Int! The offset value for the result set. sortBy String! The sorting column name of the result set. sortOrder String! The sorting order of the result set. Possible values are asc and desc."},{"location":"monitoring-and-insights/work-with-choreo-insights-api/choreo-insights-api/#platform","title":"Platform","text":"

        Represents a platform.

        Field Argument Type Description platform String! The name of the platform. count Int! The usage of the platform."},{"location":"monitoring-and-insights/work-with-choreo-insights-api/choreo-insights-api/#provider","title":"Provider","text":"

        Represents API Provider details.

        Field Argument Type Description name String! The API provider name."},{"location":"monitoring-and-insights/work-with-choreo-insights-api/choreo-insights-api/#resourceusage","title":"ResourceUsage","text":"

        Represents the usage of a single API resource.

        Field Argument Type Description apiId ID! The ID of the API. apiResourceTemplate String! The API resource template. apiMethod String! The API method. count Int! The usage of the API resource."},{"location":"monitoring-and-insights/work-with-choreo-insights-api/choreo-insights-api/#resourceusages","title":"ResourceUsages","text":"

        Represents API resource usages.

        Field Argument Type Description usage [ResourceUsage] A list with the usage of each API resource. Returns an empty array if no data is available. pagination Pagination! Pagination details."},{"location":"monitoring-and-insights/work-with-choreo-insights-api/choreo-insights-api/#slowapi","title":"SlowAPI","text":"

        A slow API identified based on the response latency (95th percentile).

        Field Argument Type Description apiId ID! The ID of the API. latency Int! Represents the latency (95th percentile) time in milliseconds (ms)."},{"location":"monitoring-and-insights/work-with-choreo-insights-api/choreo-insights-api/#subscriber","title":"Subscriber","text":"

        Represents API Subscriber details.

        Field Argument Type Description name String! The name of the API subscriber."},{"location":"monitoring-and-insights/work-with-choreo-insights-api/choreo-insights-api/#successapiusagebyapplication","title":"SuccessAPIUsageByApplication","text":"

        Represents successful usages(that have resulted in the 2xx response code) of an API by an application.

        Field Argument Type Description apiId String! The ID of the API. apiName String! The name of the API. apiVersion String! The version of the API. apiCreatorTenantDomain String! The tenant domain of the API creator. applicationId String! The application ID. applicationName String! The name of the application. applicationOwner String! The name of the application owner. count Int!"},{"location":"monitoring-and-insights/work-with-choreo-insights-api/choreo-insights-api/#successsummary","title":"SuccessSummary","text":"

        Provides the successful (2xx response code) usage summary across all the APIs.

        Field Argument Type Description summary [SuccessValue]! A list containing successful usage values. Returns an empty array if no data is available. granularity String! The granularity value for which data is retrieved."},{"location":"monitoring-and-insights/work-with-choreo-insights-api/choreo-insights-api/#successvalue","title":"SuccessValue","text":"

        Represents the successful request count (i.e., requests that have received the 2xx response code) for a single timestamp. The timestamp is calculated according to the granularity value provided.

        Field Argument Type Description timeSpan String! Represents a timestamp value that is calculated based on the specified granularity value. For example, if the granularity value is 1d, the timestamp represents the start of the day calculated adhering to the timezone provided in the time filter. e.g., timeSpan: '2021-06-21T00:00:00.0000000+05:30' requestCount Int! Represents the successful request count."},{"location":"monitoring-and-insights/work-with-choreo-insights-api/choreo-insights-api/#topapibyalertcount","title":"TopAPIByAlertCount","text":"

        Represents a top API by alert count.

        Field Argument Type Description apiId ID! The ID of the API. count Int! The alert count."},{"location":"monitoring-and-insights/work-with-choreo-insights-api/choreo-insights-api/#topapisbyalertcount","title":"TopAPIsByAlertCount","text":"

        Represents the top APIs by alert count.

        Field Argument Type Description usage [TopAPIByAlertCount] A list containing top APIs by alert count. Returns an empty array if no data is available. pagination Pagination! The pagination details."},{"location":"monitoring-and-insights/work-with-choreo-insights-api/choreo-insights-api/#totalerror","title":"TotalError","text":"

        Represents the total errors.

        Field Argument Type Description proxy Int The proxy-related error count."},{"location":"monitoring-and-insights/work-with-choreo-insights-api/choreo-insights-api/#usagebygeolocation","title":"UsageByGeoLocation","text":"

        Represents the usage of a single API in a single country.

        Field Argument Type Description country String! The name of the country. count Int! The usage of the API."},{"location":"monitoring-and-insights/work-with-choreo-insights-api/choreo-insights-api/#useragent","title":"UserAgent","text":"

        Represents a user agent.

        Field Argument Type Description userAgent String! The name of the user agent. count Int! The usage of the user agent."},{"location":"monitoring-and-insights/work-with-choreo-insights-api/choreo-insights-api/#inputs","title":"Inputs","text":""},{"location":"monitoring-and-insights/work-with-choreo-insights-api/choreo-insights-api/#apiusagebyappfilter","title":"APIUsageByAppFilter","text":"

        Filters the API usage by application results.

        Field Type Description apiIds [String] The results are filtered for the list of APIs you specify here. A maximum of five API IDs can be defined. appIds [String] The results are filtered for the list of applications you specify here. A maximum of five application IDs can be defined. subscribers [String] The results are filtered for the list of subscribers you specify here. A maximum of five subscriber IDs can be defined."},{"location":"monitoring-and-insights/work-with-choreo-insights-api/choreo-insights-api/#apiusagebybackendovertimefilter","title":"APIUsageByBackendOverTimeFilter","text":"

        Filters the results for API usage by backend over time.

        Field Type Description apiIds [String] The results are filtered for the list of APIs you specify here. A maximum of five API IDs can be defined. granularity String The granularity value that is used for data retrieval. If the granularity value is not set, the default granularity for the related time range is applied. The possible granularity values that you can specify are 1m, 15m, 1h, 1d, and 7d."},{"location":"monitoring-and-insights/work-with-choreo-insights-api/choreo-insights-api/#apiusageovertimefilter","title":"APIUsageOverTimeFilter","text":"

        Filters the results for API usage over time.

        Field Type Description apiIds [String] The results are filtered for the list of APIs you specify here. A maximum of five API IDs can be defined. appIds [String] The results are filtered for the list of applications you specify here. A maximum of five application IDs can be defined. granularity String The granularity value that is used for data retrieval. If the granularity value is not set, the default granularity for the related time range is applied. The possible granularity values that you can specify are 1m, 15m, 1h, 1d, and 7d."},{"location":"monitoring-and-insights/work-with-choreo-insights-api/choreo-insights-api/#alertsummaryfilter","title":"AlertSummaryFilter","text":"

        Filters the alerts summary results.

        Field Type Description paginationFilter PaginationFilter The pagination filter. searchFilter SearchFilter The search filter. apiIds [String] The results are filtered for the list of APIs you specify here. A maximum of five API IDs can be defined. category String The alert category by which the results need to be filtered. The available categories to select are TRAFFIC and LATENCY."},{"location":"monitoring-and-insights/work-with-choreo-insights-api/choreo-insights-api/#applicationfilter","title":"ApplicationFilter","text":"

        Filters applications by the application owner and API IDs.

        Field Type Description owner String apiIds [String] The results are filtered for the list of APIs you specify here. A maximum of five API IDs can be defined."},{"location":"monitoring-and-insights/work-with-choreo-insights-api/choreo-insights-api/#cachefilter","title":"CacheFilter","text":"

        Filters response cache results.

        Field Type Description apiId String The results are filtered by the API ID specified here. granularity String The granularity value that is used for data retrieval. If the granularity value is not set, the default granularity for the related time range is applied. The possible granularity values that you can specify are 1m, 15m, 1h, 1d, and 7d."},{"location":"monitoring-and-insights/work-with-choreo-insights-api/choreo-insights-api/#datafilter","title":"DataFilter","text":"

        Filters results by the given combination of organization, environment, and tenant.

        Field Type Description orgId String! The organization by which the results need to be filtered. It is required to specify a value for this parameter. environmentId String The environment ID by which the results need to be filtered. It is required to specify a value for this parameter. environmentIds [String] The environment IDs by which the results need to be filtered. It is required to specify a value for this parameter. tenant String! The name of the tenant by which the results need to be filtered. It is required to specify a value for this parameter. projectId String The project ID by which the results need to be filtered. It is optional to specify a value for this parameter. Note that providing a project ID with an on-prem key is not allowed."},{"location":"monitoring-and-insights/work-with-choreo-insights-api/choreo-insights-api/#devicefilter","title":"DeviceFilter","text":"

        Filters results related to devices.

        Field Type Description apiIds [String] The results are filtered for the list of APIs you specify here. A maximum of five API IDs can be defined."},{"location":"monitoring-and-insights/work-with-choreo-insights-api/choreo-insights-api/#errorcountbystatuscodefilter","title":"ErrorCountByStatusCodeFilter","text":"

        Filters errors by status code results.

        Field Type Description apiId String The results are filtered by the API ID specified here. errorType ErrorType! The type of the error. It is required to specify a value for this parameter. errorCodeType ErrorCodeType The error code type. If this parameter is not configured, both client-related error response codes (401, 404, etc.) and server-related response codes (500, 501, etc.) are included in the result set. paginationFilter PaginationFilter The pagination filter."},{"location":"monitoring-and-insights/work-with-choreo-insights-api/choreo-insights-api/#errorsbycategoryfilter","title":"ErrorsByCategoryFilter","text":"

        Filters errors by category results.

        Field Type Description apiId String The ID of the API. categories [String] The list of categories by which the results need to be filtered. Category values that you can specify here are AUTH, TARGET_CONNECTIVITY, THROTTLED, and OTHER. granularity String The granularity value that is used for data retrieval. If the granularity value is not set, the default granularity for the related time range is applied. The possible granularity values that you can specify are 1m, 15m, 1h, 1d, and 7d."},{"location":"monitoring-and-insights/work-with-choreo-insights-api/choreo-insights-api/#errorsbystatuscodefilter","title":"ErrorsByStatusCodeFilter","text":"

        Filters errors by status code results.

        Field Type Description apiId String The results are filtered by the API ID specified here. granularity String The granularity value that is used for data retrieval. If the granularity value is not set, the default granularity for the related time range is applied. The possible granularity values that you can specify are 1m, 15m, 1h, 1d, and 7d."},{"location":"monitoring-and-insights/work-with-choreo-insights-api/choreo-insights-api/#errorsdetailsfilter","title":"ErrorsDetailsFilter","text":"

        Filters the results for error details.

        Field Type Description apiId String The results are filtered by the API ID specified here. appId String The application ID by which the results need to be filtered. category String The error category by which the results need to be filtered. The error category that you can specify here must be one of the AUTH TARGET_CONNECTIVITY, THROTTLED, and OTHER values. granularity String The granularity value that is used for data retrieval. If the granularity value is not set, the default granularity for the related time range is applied. The possible granularity values that you can specify are 1m, 15m, 1h, 1d, and 7d. paginationFilter PaginationFilter The pagination filter. searchFilter SearchFilter The search filter."},{"location":"monitoring-and-insights/work-with-choreo-insights-api/choreo-insights-api/#geolocationfilter","title":"GeoLocationFilter","text":"

        Filters the API usage by geolocation results.

        Field Type Description apiIds [String] The results are filtered for the list of APIs you specify here."},{"location":"monitoring-and-insights/work-with-choreo-insights-api/choreo-insights-api/#latencyfilter","title":"LatencyFilter","text":"

        Filters latency results.

        Field Type Description apiId String! The results are filtered by the API ID specified here. It is required to specify a value for this parameter. granularity String The granularity value that is used for data retrieval. If the granularity value is not set, the default granularity for the related time range is applied. The possible granularity values that you can specify are 1m, 15m, 1h, 1d, and 7d."},{"location":"monitoring-and-insights/work-with-choreo-insights-api/choreo-insights-api/#latencysummaryfilter","title":"LatencySummaryFilter","text":"

        Filters latency summary results.

        Field Type Description apiId String The results are filtered by the API ID specified here. granularity String The granularity value that is used for data retrieval. If the granularity value is not set, the default granularity for the related time range is applied. The possible granularity values that you can specify are 1m, 15m, 1h, 1d, and 7d."},{"location":"monitoring-and-insights/work-with-choreo-insights-api/choreo-insights-api/#orgfilter","title":"OrgFilter","text":"

        Filters results for the given organization.

        Field Type Description orgId String! The ID of the organization by which the results need to be filtered. It is required to specify a value for this parameter."},{"location":"monitoring-and-insights/work-with-choreo-insights-api/choreo-insights-api/#paginationfilter","title":"PaginationFilter","text":"

        Filters related to pagination.

        Field Type Description limit Int The total number of rows in the result set. This value must be a positive integer. If this limit value is not set, the total number of rows is five by default. offset Int The offset value to set when filtering results. This value must be zero or a positive integer. If you do not specify an offset value, the default offset value (i.e., 0) applies. sortBy String The column name by which the results are sorted. If the sortBy value is not set, the default column of the related operation that is available for sorting purposes is used. sortOrder String The order in which the results are sorted. Possible values are asc (to sort in ascending order) and desc (to sort in descending order). If no value is specified, the results are sorted in ascending order by default (except for count-specific operations such as getTopAPIsByAlertCount where the results are always sorted in descending order)."},{"location":"monitoring-and-insights/work-with-choreo-insights-api/choreo-insights-api/#resourceusagefilter","title":"ResourceUsageFilter","text":"

        Filters resource usage results.

        Field Type Description paginationFilter PaginationFilter The pagination filter. searchFilter SearchFilter The search filter."},{"location":"monitoring-and-insights/work-with-choreo-insights-api/choreo-insights-api/#searchfilter","title":"SearchFilter","text":"

        Filters results by searching matching results for the provided search text.

        Field Type Description apiIds [String] The list of API IDs that need to be searched with the given search text. Note that it is not possible to define API IDs without a search text in the search filter. searchText String! Text which needs to be searched among the results. It is required to specify a value for this parameter."},{"location":"monitoring-and-insights/work-with-choreo-insights-api/choreo-insights-api/#subscriberfilter","title":"SubscriberFilter","text":"

        Filters the subscriber results.

        Field Type Description apiIds [String] The results are filtered for the list of APIs you specify here. A maximum of five API IDs can be defined."},{"location":"monitoring-and-insights/work-with-choreo-insights-api/choreo-insights-api/#successapiusagebyappfilter","title":"SuccessAPIUsageByAppFilter","text":"

        Filters successful API usage by application results.

        Field Type Description apiIds [String] The list of API IDs by which the results need to be filtered. tenantDomains [String] The tenant domain name by which the results need to be filtered."},{"location":"monitoring-and-insights/work-with-choreo-insights-api/choreo-insights-api/#tenantdatafilter","title":"TenantDataFilter","text":"

        Filters results by the tenant.

        Field Type Description orgId String! The ID of the organization by which the results need to be filtered. It is required to specify a value for this parameter. envId String The ID of the environment by which the results need to be filtered. It is required to specify a value for this parameter. environmentIds [String] The environment IDs by which the results need to be filtered. It is required to specify a value for this parameter."},{"location":"monitoring-and-insights/work-with-choreo-insights-api/choreo-insights-api/#timefilter","title":"TimeFilter","text":"

        Filters results by the provided date range.

        Field Type Description from String! The start date of the time range. The date specified here must be a date earlier than the date specified via the to parameter. If the defined date and time entry do not have a timezone, the UTC time zone (z) is used. It is required to specify a value for this parameter. e.g., '2021-08-16T12:00:00.000+05:30'. to String! The end date of the time range. The date specified here must be a date later than the date specified via the from parameter. If the defined date and time entry do not have a timezone, the UTC time zone (z) is used. It is required to specify a value for this parameter. e.g., '2021-08-16T12:30:00.000+05:30'."},{"location":"monitoring-and-insights/work-with-choreo-insights-api/choreo-insights-api/#topapisbyalertcountfilter","title":"TopAPIsByAlertCountFilter","text":"

        Filters the top APIs by alert count results.

        Field Type Description paginationFilter PaginationFilter The pagination filter. searchFilter SearchFilter The search filter."},{"location":"monitoring-and-insights/work-with-choreo-insights-api/choreo-insights-api/#enums","title":"Enums","text":""},{"location":"monitoring-and-insights/work-with-choreo-insights-api/choreo-insights-api/#environmenttype","title":"EnvironmentType","text":"

        Represents an error type.

        Value Description CHOREO The Choreo environments. CHOREO_PRIVATE The private data-plane Choreo environments. ON_PREM The On-Premise environments."},{"location":"monitoring-and-insights/work-with-choreo-insights-api/choreo-insights-api/#errorcodetype","title":"ErrorCodeType","text":"

        Represents an error code type.

        Value Description _4XX The client-side errors. _5XX The server-side errors."},{"location":"monitoring-and-insights/work-with-choreo-insights-api/choreo-insights-api/#errortype","title":"ErrorType","text":"

        Represents an error type.

        Value Description PROXY The proxy-related errors. TARGET The target-related errors."},{"location":"monitoring-and-insights/work-with-choreo-insights-api/choreo-insights-api/#groupbyfield","title":"GroupByField","text":"

        Represents an groupByField used in CustomReports.

        Value Description API_NAME The API name. API_VERSION The API version. API_RESOURCE_TEMPLATE The API resource template. API_METHOD The API method. API_CREATOR The API creator. APPLICATION_NAME The name of the application. APPLICATION_OWNER The owner of the application. DESTINATION The destination. USER_AGENT The user Agent. PLATFORM The platform. TARGET_RESPONSE_CODE The target response code."},{"location":"monitoring-and-insights/work-with-choreo-insights-api/choreo-insights-api/#metric","title":"Metric","text":"

        Represents a metric used in CustomReports.

        Value Description HIT_COUNT The number of API calls. RESPONSE_CACHE_HIT The number of API calls that used the response cache. REQUEST_MEDIATION_LATENCY The request mediation latency. RESPONSE_MEDIATION_LATENCY The response mediation latency. BACKEND_LATENCY The backend latency. TOTAL_LATENCY The total latency. API_ERRORS The number of hits for which API errors are returned. TARGET_ERRORS The number of hits for which target errors are returned."},{"location":"monitoring-and-insights/work-with-choreo-insights-api/choreo-insights-api/#scalars","title":"Scalars","text":""},{"location":"monitoring-and-insights/work-with-choreo-insights-api/choreo-insights-api/#boolean","title":"Boolean","text":"

        The Boolean scalar type represents true or false.

        "},{"location":"monitoring-and-insights/work-with-choreo-insights-api/choreo-insights-api/#float","title":"Float","text":"

        The Float scalar type represents signed double-precision fractional values as specified by IEEE 754.

        "},{"location":"monitoring-and-insights/work-with-choreo-insights-api/choreo-insights-api/#id","title":"ID","text":"

        The ID scalar type represents a unique identifier, often used to re-fetch an object or as the key for a cache. The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When expected as an input type, any string (such as \"4\") or integer (such as 4) input value is accepted as an ID.

        "},{"location":"monitoring-and-insights/work-with-choreo-insights-api/choreo-insights-api/#int","title":"Int","text":"

        The Int scalar type represents non-fractional signed whole numeric values. Int can represent values between -(2^31) and 2^31 - 1.

        "},{"location":"monitoring-and-insights/work-with-choreo-insights-api/choreo-insights-api/#string","title":"String","text":"

        The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

        "},{"location":"quick-start-guides/deploy-a-web-application-that-consumes-a-backend-service/","title":"Deploy a Web Application that Consumes a Backend Service","text":"

        Choreo is an Internal Developer Platform (IDevP) that streamlines the entire process of building, deploying, monitoring, and managing your cloud-native applications easily.

        In this quick start guide, you will explore how to expose a service endpoint via Choreo and securely consume the service from a web application. You will use a simple reading list web application with a sign-in page and functionality to interact with a secure backend service. You will also use Choreo's managed authentication to easily set up authentication for your web application without having to dive into the details of security protocols. The application will allow users to sign in and view their reading lists, add books to a reading list, delete books from the reading list, and sign out of the application effortlessly.

        This guide walks you through the following steps:

        • Deploy and test a service component.
        • Create a web application to consume the exposed service.
        • Create a connection to the deployed service.
        • Enable managed authentication and deploy the web application.
        • Consume the deployed service via the web application.
        "},{"location":"quick-start-guides/deploy-a-web-application-that-consumes-a-backend-service/#prerequisites","title":"Prerequisites","text":"

        Before you try out this guide, complete the following:

        1. Create a GitHub repository to save the service implementation. For this guide, you can fork the Choreo sample book list app repository.

        2. If you are signing in to the Choreo Console for the first time, create an organization as follows:

          1. Go to https://console.choreo.dev/, and sign in using your Google, GitHub, or Microsoft account.
          2. Enter a unique organization name. For example, Stark Industries.
          3. Read and accept the privacy policy and terms of use.
          4. Click Create.

          This creates the organization and opens the organization home page.

        "},{"location":"quick-start-guides/deploy-a-web-application-that-consumes-a-backend-service/#step-1-create-a-project","title":"Step 1: Create a project","text":"

        Follow the steps given below to create a project:

        1. Go to https://console.choreo.dev/ and sign in. This opens the organization home page.
        2. On the organization home page, click + Create Project.

        3. Enter a display name, unique name, and description for the project. You can enter the values given below:

          Tip

          In the Name field, you must specify a name to uniquely identify your project in various contexts. The value is editable only at the time you create the project. You cannot change the name after you create the project.

          Field Value Project Display Name Sample project Name sample-project Project Description My sample project

        4. Click Create. This creates the project and opens the project home page.

        "},{"location":"quick-start-guides/deploy-a-web-application-that-consumes-a-backend-service/#step-2-connect-your-sample-repository-and-configure-the-sample-service","title":"Step 2: Connect your sample repository and configure the sample service","text":"

        To connect to the repository you forked in the prerequisites and configure the sample service, follow the steps given below:

        1. On the project home page, click Start under Create Multiple Components.
        2. Go to the GitHub tab.

        3. To allow Choreo to connect to your GitHub account, click Authorize with GitHub. If you have not already connected your GitHub repository to Choreo, enter your GitHub credentials and select the repository you created in the prerequisites section to install the Choreo GitHub App.

          Alternatively, you can paste the Choreo sample book list app repository URL in the Provide Repository URL field to connect to it without requiring authorization from the Choreo Apps GitHub application. However, authorizing the repository with the Choreo GitHub App is necessary if you want to enable Auto Deploy for the component.

          Note

          The Choreo GitHub App requires the following permissions:

          • Read and write access to code and pull requests.
          • Read access to issues and metadata.

          You can revoke access if you do not want Choreo to have access to your GitHub account. However, write access is exclusively utilized for sending pull requests to a user repository. Choreo will not directly push any changes to a repository.

        4. Enter the following information:

          Field Value Organization Your GitHub account Repository choreo-sample-book-list-app Branch main

        5. In the Add Component Directories pane under Configure Components, click the + icon corresponding to reading-list-service.

        6. In the Component Configuration dialog that opens, specify values as follows for each of the fields:

          Field Value Component Display Name Reading List Service Component Name reading-list-service Path reading-list-service Component Type Service Buildpack NodeJS Language Version 20.x.x

        7. Click Save. This adds the Reading List Service component to the Configured Components pane.

        8. Click Finish. This initializes the service with the implementation from your GitHub repository and takes you to the project home page.

          You can see the Reading List Service component listed under Component Listing on the project home page.

        "},{"location":"quick-start-guides/deploy-a-web-application-that-consumes-a-backend-service/#step-3-build-the-service","title":"Step 3: Build the service","text":"

        To build the service, follow the steps given below:

        1. On the project home page, click the Reading List Service component listed under Component Listing. This takes you to the component overview page.
        2. In the left navigation menu, click Build.
        3. In the Builds pane, click Build Latest.

        !!! note Building the service component may take a while. You can track the progress via the logs in the Build Details pane. Once the build process is complete, the build status changes to Success.

        "},{"location":"quick-start-guides/deploy-a-web-application-that-consumes-a-backend-service/#step-4-deploy-the-service","title":"Step 4: Deploy the service","text":"

        For the REST endpoint of the service to be invokable, you need to deploy it. To deploy the service, follow the steps given below:

        1. In the left navigation menu, click Deploy.
        2. In the Set Up card, click Configure & Deploy.
        3. In the Environment Configurations pane that opens, click Next to skip the configuration.
        4. In the File Mount pane that opens, click Next to skip the configuration.
        5. In the Endpoint Details pane that opens, verify that the Network Visibility is set to Public. This setting securely exposes the endpoint for consumption.
        6. Click Deploy. This deploys the service to the development environment and lists the service in the Choreo Marketplace.
        "},{"location":"quick-start-guides/deploy-a-web-application-that-consumes-a-backend-service/#step-5-test-the-service","title":"Step 5: Test the service","text":"

        To test the endpoint via the integrated OpenAPI Console in Choreo, follow the steps given below:

        1. In the Choreo Console left navigation menu, click Test and then click Console.
        2. In the OpenAPI Console that opens, select Development from the environment drop-down list.
        3. In the Endpoint list, select Books REST Endpoint.
        4. Expand the GET/books method, click Try it out, then click Execute.
        5. Click .
        6. Check the Server Response section. You will see an empty response. You can add an entry using the POST method and retry the GET/books method again.
        7. Expand the POST/books method and click Try it out.

        8. Update the request body so that the parameters have the values given below:

          Parameter Value author Bram Stoker status to_read title Dracula

          The request body should look as follows:

            {\n\"author\": \"Bram Stoker\",\n\"status\": \"to_read\",\n\"title\": \"Dracula\"\n}\n
          9. Click Execute.

          Check the Server Response section. On successful invocation, you will receive the 201 HTTP code.

        Similarly, you can expand and try out the GET and DELETE methods.

        "},{"location":"quick-start-guides/deploy-a-web-application-that-consumes-a-backend-service/#step-6-consume-the-service","title":"Step 6: Consume the service","text":"

        Now that the Reading List Service is deployed and available in the Choreo Marketplace, application developers can discover the service via the Marketplace and consume it.

        In this section of the guide, you will deploy a sample front-end application to consume the service. This application will serve as the interface for users to interact with the reading list. The sample application used in this guide is designed to personalize the book lists based on the user ID that it obtains from its identity provider.

        To host the front-end application in Choreo, you will create a web application component, set up authentication for it, and deploy it. To establish a connection between your web application and the deployed service, you will create a Connection.

        "},{"location":"quick-start-guides/deploy-a-web-application-that-consumes-a-backend-service/#step-61-create-a-web-application-to-consume-the-service","title":"Step 6.1: Create a web application to consume the service","text":"

        To create a web application component, follow the steps given below:

        1. In the Choreo Console header, click the Project list and select the project that you created in step 1.
        2. On the project home page, click + Create under Component Listing.
        3. Click the Web Application card.

        4. Enter a display name, unique name, and a description to create the web application. You can enter the values given below:

          Info

          In the Component Name field, you must specify a name to uniquely identify the component in various contexts. The value is editable only at the time you create the component. You cannot change the name after you create the component.

          Field Value Component Display Name Reading List Web App Component Name reading-list-web-app Description Front-end application for the reading list service

        5. Go to the GitHub tab.

        6. To allow Choreo to connect to your GitHub account, click Authorize with GitHub. If you have not already connected your GitHub repository to Choreo, enter your GitHub credentials and select the repository you created in the prerequisites section to install the Choreo GitHub App.

          Alternatively, you can paste the Choreo sample Book List Service repository URL in the Provide Repository URL field to connect to it without requiring authorization from the Choreo Apps GitHub application. However, authorizing the repository with the Choreo GitHub App is necessary if you want to enable Auto Deploy for the component.

          Note

          The Choreo GitHub App requires the following permissions:

          • Read and write access to code and pull requests.
          • Read access to issues and metadata.

          You can revoke access if you do not want Choreo to have access to your GitHub account. However, write access is exclusively utilized for sending pull requests to a user repository. Choreo will not directly push any changes to a repository.

        7. Enter the following information:

          Field Description Organization Your GitHub account Repository choreo-sample-book-list-app Branch main

        8. Select React as the buildpack because the sample front-end application is a React application built with Vite.

        9. Enter the following information:

          Field Value Project Directory /choreo-sample-book-list-app/reading-list-front-end-with-managed-auth Build Command npm install && npm run build Build Path dist Node Version 18

        10. Click Create. This initializes the component with the implementation from your GitHub repository and takes you to the Overview page of the component.

        "},{"location":"quick-start-guides/deploy-a-web-application-that-consumes-a-backend-service/#step-62-create-a-connection-between-the-web-application-and-the-deployed-service","title":"Step 6.2: Create a connection between the web application and the deployed service","text":"

        A connection allows you to integrate the service you intend to deploy on Choreo with other services on Choreo or external resources. For more information on Choreo Connections refer to the Connection documentation.

        To establish a connection between the web application you created and the deployed service, follow the steps given below:

        1. In the left navigation menu, click Dependencies and then click Connections.
        2. Click + Create.
        3. In the Select a Service pane, click Reading List Service.`

        4. Specify values as follows for each of the fields:

          Field Value Name Reading List Connection Description Connection to the reading list

        5. Click Create. This creates the connection and displays the service URL of the connection for each environment the service is deployed in. In this guide, you will see the service URL for the Development environment. You can copy the service URL to use when you configure the web application before deploying it.

        "},{"location":"quick-start-guides/deploy-a-web-application-that-consumes-a-backend-service/#step-63-build-the-web-application-component","title":"Step 6.3: Build the web application component","text":"

        To build the web application, follow the steps given below:

        1. In the left navigation menu, click Build.
        2. In the Builds pane, click Build Latest.

        !!! note Building the service component may take a while. You can track the progress via the logs in the Build Details pane. Once the build process is complete, the build status changes to Success.

        "},{"location":"quick-start-guides/deploy-a-web-application-that-consumes-a-backend-service/#step-64-configure-and-deploy-the-web-application","title":"Step 6.4: Configure and deploy the web application","text":"

        In this step, you will configure managed authentication, create a user to access the web application, and then deploy the web application. For more information on Choreo's managed authentication capability, see the Managed Authentication documentation.

        To configure managed authentication, follow the steps given below:

        1. In the left navigation menu, click Deploy.
        2. In the Set Up card, click Configure and Deploy. This opens the Configure & Deploy pane, where you can specify values for the mount file.

        3. Specify the following in the config.js file mount.

          • You must replace <Service URL> with the value that you copied when creating a connection to the Reading List Service in step 6.2.

            window.configs = {\napiUrl: '<Service URL>',\n};\n

          Tip

          You can refer to the configuration file mounted at /app/public as ./public/config.js within your web application.

        4. Click Next. This opens the Authentication pane.

        5. Under Authentication Settings, make sure that you have the Managed authentication with Choreo toggle enabled.

          Tip

          Managed authentication is enabled by default when you create a web application using React, Angular, or Vue.js buildpacks.

        6. Specify values as follows for each of the fields:

          Field Value Post Login Path / Post Logout Path / Error Path /

        Next, you can create a user to access the web application.

        To create a user to access the readingListApp application, follow the steps given below:

        1. Under Manage Users, click + Create.

        2. To proceed with creating a user with the populated username and password, click Create. Make sure you copy the populated username and password to use when you test the front-end application.

          Tip

          • By default, your test user base consists of a demo user. For instructions on how to modify the test user base, see Configure a User Store with the Built-In Identity Provider.

        Now, you can deploy the web application.

        To deploy the web application and obtain the URL to access it, follow the steps given below:

        1. In the Authentication pane, click Deploy. The deployment may take a few minutes to complete.
        2. Once you deploy the web application, copy the Web App URL from the development environment card.
        3. Navigate to the web app URL. You can verify that you have successfully hosted the web application.
        "},{"location":"quick-start-guides/deploy-a-web-application-that-consumes-a-backend-service/#step-7-test-the-front-end-application","title":"Step 7: Test the front-end application","text":"

        To test the front-end application and send requests to the Reading List Service via it, follow the steps given below:

        1. Access the front-end application via its web URL that you copied in the above step.

        2. Click Login, and sign in with the credentials of the user that you created.

          The application opens as follows.

        3. Add three new reading items with different statuses.

          For example, the details can be as follows:

          Title Author Status The Museum of Innocence Orhan Pamuk reading The Remains of the Day Kazuo Ishiguro to_read David Copperfield Charles Dickens read

          To add each record, follow the steps given below:

          1. Click + Add New.
          2. Enter values for the Name, Author, and Status fields.
          3. Click Save.

          Three tabs open for each status. To delete a reading list item, you can click Delete.

        To verify whether the reading list is personalized for each user, you can sign in as a different user. The reading list items you entered above will not appear for the other user.

        Congratulations! You have successfully exposed a service endpoint via Choreo and securely consumed it from a web application.

        After you have successfully tested your service and web application, you can now try out various other Choreo features such as managing, observing, DevOps, etc., similar to any other component type within Choreo.

        "},{"location":"quick-start-guides/deploy-your-first-service/","title":"Deploy Your First Service","text":"

        Choreo, an Internal Developer Platform (IDevP), simplifies the deployment, monitoring, and management of your cloud-native services, allowing you to focus on innovation and implementation.

        Choreo allows you to easily deploy services you've created in your preferred programming language in just a few steps.

        In this guide, you will:

        • Use a pre-implemented service that has resources to maintain a book list.
        • Build and deploy the service in Choreo using the Nodejs buildpack. It runs on port 8080.
        • Test the service.

        For a video tutorial that walks you through these steps, see Deploy Your First Service with Choreo.

        "},{"location":"quick-start-guides/deploy-your-first-service/#prerequisites","title":"Prerequisites","text":"

        1. You must have a GitHub account with a repository that contains your service implementation. To proceed with the steps in this guide, you can fork the Choreo sample book list service repository, which contains the sample for this guide.

        2. If you are signing in to the Choreo Console for the first time, create an organization as follows:

          1. Go to https://console.choreo.dev/, and sign in using your Google, GitHub, or Microsoft account.
          2. Enter a unique organization name. For example, Stark Industries.
          3. Read and accept the privacy policy and terms of use.
          4. Click Create.

          This creates the organization and opens the organization home page.

        "},{"location":"quick-start-guides/deploy-your-first-service/#learn-the-repository-file-structure","title":"Learn the repository file structure","text":"

        Let's familiarize ourselves with the key files in this sample application. The below table gives a brief overview of the important files in the sample book list service.

        Note

        The following file paths are relative to the path <choreo-sample-book-list-service>/.

        Filepath Description app.mjs The Node.js (JavaScript) based service code. .choreo/endpoints.yaml Choreo-specific configuration that provides information about how Choreo exposes the service. openapi.yaml OpenAPI contract of the service. This is required to publish our service as a managed API. This openapi.yaml file is referenced by the .choreo/endpoints.yaml.

        Let's get started!

        "},{"location":"quick-start-guides/deploy-your-first-service/#step-1-create-a-project","title":"Step 1: Create a project","text":"

        Follow the steps given below to create a project:

        1. Go to https://console.choreo.dev/ and sign in. This opens the organization home page.
        2. On the organization home page, click + Create Project.

        3. Enter a display name, unique name, and description for the project. You can enter the values given below:

          Info

          In the Name field, you must specify a name to uniquely identify your project in various contexts. The value is editable only at the time you create the project. You cannot change the name after you create the project.

          Field Value Project Display Name Book List Project Name book-list-project Project Description My sample project

        4. Click Create. This creates the project and takes you to the project home page.

        "},{"location":"quick-start-guides/deploy-your-first-service/#step-2-create-a-service-component","title":"Step 2: Create a service component","text":"

        Let's create a service component by following these steps:

        1. On the project home page, click Service under Create a Component.

        2. Enter a unique name and a description for the service. For this guide, let's enter the following values:

          Field Value Component Display Name Book List Description Gets the book list

        3. Go to the GitHub tab.

        4. To allow Choreo to connect to your GitHub account, click Authorize with GitHub. If you have not already connected your GitHub repository to Choreo, enter your GitHub credentials and select the repository you created in the prerequisites section to install the Choreo GitHub App.

          Alternatively, you can paste the Choreo sample Book List Service repository URL in the Provide Repository URL field to connect to it without requiring authorization from the Choreo Apps GitHub application. However, authorizing the repository with the Choreo GitHub App is necessary if you want to enable Auto Deploy for the component.

          Note

          The Choreo GitHub App requires the following permissions:

          • Read and write access to code and pull requests.
          • Read access to issues and metadata.

          You can revoke access if you do not want Choreo to have access to your GitHub account. However, write access is exclusively utilized for sending pull requests to a user repository. Choreo will not directly push any changes to a repository.

        5. Enter the following information:

          Field Description Organization Your GitHub account Repository choreo-sample-book-list-service Branch main

        6. Select the NodeJS buildpack.

        7. Enter the following information.

          Field Description NodeJS Project Directory / Language Version 20.x.x

        8. Click Create.

        You have successfully created a Service component with the NodeJS buildpack. Now let's build and deploy the service.

        "},{"location":"quick-start-guides/deploy-your-first-service/#step-3-build-and-deploy","title":"Step 3: Build and deploy","text":"

        Now that the source repository is connected and Choreo has set up the endpoints based on the repository's configuration, it's time to proceed with building the service. Choreo will create a Docker image in the build process. You can then deploy the built Docker image and test the book list service.

        "},{"location":"quick-start-guides/deploy-your-first-service/#step-31-build","title":"Step 3.1: Build","text":"

        To build the service, follow these steps:

        1. On the project home page, click the Book List component listed under Component Listing. This takes you to the component overview page.
        2. In the left navigation, click Build.
        3. Click Build Latest.

        !!! note Building the service component may take a while. You can track the progress via the logs in the Build Details pane. Once the build process is complete, the build status changes to Success.

        "},{"location":"quick-start-guides/deploy-your-first-service/#step-32-deploy","title":"Step 3.2: Deploy","text":"

        Now you are ready to deploy the service. Follow these steps:

        1. In the left navigation menu, click Deploy.
        2. On the Set Up card, click Configure & Deploy.
        3. In the Environment Configurations pane, click Next.
        4. In the File Mount pane, click Next.

        5. Review the Endpoint Details and click Deploy.

          Note

          Deploying the service component may take a while. You can track the progress by observing the logs. Once the deployment is complete, the build status changes to Active on the Development environment card.

        "},{"location":"quick-start-guides/deploy-your-first-service/#step-4-test-the-service","title":"Step 4: Test the service","text":"

        To test the Book List service via the integrated OpenAPI Console in Choreo, follow the steps given below:

        1. In the Choreo Console left navigation menu, click Test and then click Console.
        2. In the OpenAPI Console that opens, select Development from the environment drop-down list.
        3. In the Endpoint list, select Books REST Endpoint.
        4. Expand the GET /books method and click Try it out.
        5. Click Execute.
        6. Check the Server Response section.

        Similarly, you can expand and try out the other methods.

        After you have successfully tested your service, you can now try out various other Choreo features such as managing, observing, DevOps, etc., similar to any other component type within Choreo.

        "},{"location":"quick-start-guides/deploy-your-first-static-web-application/","title":"Deploy Your First Static Web Application","text":"

        Choreo is an internal developer platform as a service that takes care of the complexities of building platforms, allowing application developers to focus on innovation and implementation. Choreo streamlines the entire process of building, deploying, monitoring, and managing your cloud-native applications.

        In this quick start guide, you will explore how easy it is to deploy a web application using Choreo. Here, you will use a simple web application designed to add tasks to a to-do list.

        This guide walks you through the following steps:

        • Create a project.
        • Create a Web Application component and connect it to the GitHub repository that includes the web application implementation.
        • Build the web application.
        • Deploy the web application and access it.

        For a video tutorial that walks you through these steps, see Deploy a Static Web App on Choreo.

        "},{"location":"quick-start-guides/deploy-your-first-static-web-application/#prerequisites","title":"Prerequisites","text":"

        Before you try out this guide, complete the following:

        1. Fork the choreo-sample-todo-list-app repository, which contains the sample for this guide.

        2. If you are signing in to the Choreo Console for the first time, create an organization as follows:

          1. Go to https://console.choreo.dev/, and sign in using your Google, GitHub, or Microsoft account.
          2. Enter a unique organization name. For example, Stark Industries.
          3. Read and accept the privacy policy and terms of use.
          4. Click Create.

          This creates the organization and opens the organization home page.

        "},{"location":"quick-start-guides/deploy-your-first-static-web-application/#step-1-create-a-project","title":"Step 1: Create a project","text":"

        Follow the steps given below to create a project:

        1. Go to https://console.choreo.dev/ and sign in. This opens the organization home page.
        2. On the organization home page, click + Create Project.

        3. Enter a display name, unique name, and description for the project. You can enter the values given below:

          Tip

          In the Name field, you must specify a name to uniquely identify your project in various contexts. The value is editable only at the time you create the project. You cannot change the name after you create the project.

          Field Value Project Display Name Sample project Name sample-project Project Description My sample project

        4. Click Create. This creates the project and opens the project home page.

        "},{"location":"quick-start-guides/deploy-your-first-static-web-application/#step-2-create-a-web-application-component","title":"Step 2: Create a Web Application component","text":"

        To create a Web Application component, follow the steps given below:

        1. On the project home page, click Web Application under Create a Component.
        2. Enter a unique name and a description for the web application.
        3. Go to the GitHub tab.

        4. To allow Choreo to connect to your GitHub account, click Authorize with GitHub. If you have not already connected your GitHub repository to Choreo, enter your GitHub credentials and select the repository you created in the prerequisites section to install the Choreo GitHub App.

          Alternatively, you can paste the choreo-sample-todo-list-app repository URL in the Provide Repository URL field to connect to it without requiring authorization from the Choreo Apps GitHub application. However, authorizing the repository with the Choreo GitHub App is necessary if you want to enable Auto Deploy for the component.

          Note

          The Choreo GitHub App requires the following permissions:

          • Read and write access to code and pull requests.
          • Read access to issues and metadata.

          You can revoke access if you do not want Choreo to have access to your GitHub account. However, write access is exclusively utilized for sending pull requests to a user repository. Choreo will not directly push any changes to a repository.

        5. Enter the following information:

          Field Value Organization Your GitHub account Repository choreo-sample-todo-list-app Branch main

        6. Select NodeJS as the Buildpack

        7. Enter the following information:

          Field Value NodeJS Project Directory / Language Version 20.x.x Port 8080

        8. Click Create. Choreo initializes the component with the sample implementation and opens the Overview page of the component.

        Now let's build and deploy the web application.

        "},{"location":"quick-start-guides/deploy-your-first-static-web-application/#step-3-build-your-web-application","title":"Step 3: Build your web application","text":"

        To build the web application, follow the steps given below:

        1. In the left navigation menu, click Build.

        2. In the Builds pane, click Build Latest.

          Note

          Building the component may take a while. You can track the progress via the logs in the Build Details pane. Once the build process is complete, the build status changes to Success.

        Now you can proceed to deploy your web application.

        "},{"location":"quick-start-guides/deploy-your-first-static-web-application/#step-4-deploy-and-access-your-web-application","title":"Step 4: Deploy and access your web application","text":"
        1. In the left navigation menu, click Deploy.
        2. In the Set Up card, click Configure and Deploy. This opens the Configure & Deploy pane, where you can add a file mount if necessary. In this guide you will not add a file mount.
        3. Click Deploy. The deployment to the Development environment may take a few minutes to complete. On successful deployment, you will see the Deployment Status as Active in the Development card.
        4. To verify that you have successfully hosted the web application, click the Web App URL on the Development card. This takes you to the web application. You can try creating one or more new tasks by specifying an appropriate task ID and task label.

        After you have successfully tested your web application, you can now try out various other Choreo features such as observability, DevOps, etc., similar to any other component type within Choreo.

        "},{"location":"references/choreo-limitations/","title":"Choreo Limitations","text":"

        Explore key limitations in Choreo, covering areas like HTTP request parameters, components, applications, and API definition files. You can gain insights into the limitations to enhance your understanding and optimize your use of Choreo effectively.

        "},{"location":"references/choreo-limitations/#api-management-limits","title":"API management limits","text":"

        Below are key limitations when working with APIs in Choreo:

        Resource Limit Maximum request payload 10 MB URL size 2 KB Request header
        • Request Headers total: 40 KB
        • Max Single Request header: 10 KB
        Total request duration
        • Minimum: 10 seconds
        • Default: 1 minute
        • Maximum: 5 minutes
        Size for API Definition (OpenAPI document) 10 Mb Number of APIs for PDP 1000 API deployments Number of APIs per organization (free tier) 5 APIs for free users Number of Developer Portal applications per organization (free tier) 10 applications for free users"},{"location":"references/choreo-limitations/#choreo-cloud-data-plane-limits","title":"Choreo Cloud Data Plane limits","text":"

        Below are key limitations when working with web applications in the Choreo cloud data plane:

        Resource Limit Request size limit (including headers, cookies, and payloads) 256 KB Response body size limit 20 MB Number of open ports permitted per web application 1 While it is possible to have multiple ports open for project-level communication within a data plane, incoming internet traffic can only be directed to a single port. This contrasts with Service-type components, which allow for multiple endpoints."},{"location":"references/faq/","title":"Frequently Asked Questions","text":""},{"location":"references/faq/#general","title":"General","text":""},{"location":"references/faq/#q-what-is-choreo","title":"Q: What is Choreo?","text":"

        Choreo is an internal developer platform designed to accelerate the creation of digital experiences. With Choreo, you can effortlessly build, deploy, monitor, and manage your cloud native applications. Our goal is to enhance developer productivity and enable innovation.

        "},{"location":"references/faq/#q-what-is-an-organization-in-choreo","title":"Q: What is an organization in Choreo?","text":"

        An organization is a logical grouping of users and their resources. It may represent a company, community, or a single user. Users can belong to multiple organizations, and each organization can have different roles assigned to its users to control access to Choreo features.

        "},{"location":"references/faq/#q-what-is-a-project-in-choreo","title":"Q: What is a project in Choreo?","text":"

        A project is a logical grouping of related components to help you organize your work. Each project provides runtime isolation through namespaces when you deploy components.

        "},{"location":"references/faq/#q-what-is-a-component-in-choreo","title":"Q: What is a component in Choreo?","text":"

        A component is a workload designed to run on Choreo. Examples of components include integrations, APIs, microservices, manual/scheduled jobs, web apps, and triggers.

        "},{"location":"references/faq/#q-what-is-the-difference-between-an-internal-and-external-api","title":"Q: What is the difference between an internal and external API?","text":"

        In Choreo, you can publish an API as an internal or an external API. A user or an application can access an external API publicly over the internet, whereas an internal API is only accessible through other components within the same organization.

        "},{"location":"references/faq/#q-what-is-a-connector-in-choreo-marketplace","title":"Q: What is a connector in Choreo Marketplace?","text":"

        A connector is a reusable Ballerina package that simplifies connecting to external or internal systems and APIs, such as Salesforce, SAP, GitHub, and Twilio. You can use the connectors available in the Choreo marketplace to implement your integration use cases. Connectors can be created and published by both WSO2 and Choreo users.

        "},{"location":"references/faq/#q-what-is-a-trigger-in-choreo-marketplace","title":"Q: What is a trigger in Choreo Marketplace?","text":"

        A trigger is a construct that enables users to receive known event payloads from external systems, facilitating event-driven programming.

        "},{"location":"references/faq/#q-what-is-a-sampletemplate-in-choreo","title":"Q: What is a sample/template in Choreo?","text":"

        A sample or template is a prebuilt Ballerina program that covers a popular integration use case or pattern. Examples include connecting Salesforce to Slack or implementing content-based routing.

        "},{"location":"references/faq/#q-what-are-the-support-options-in-choreo","title":"Q: What are the support options in Choreo?","text":"

        You can find information about our support plans, including free, basic, and enterprise options at https://wso2.com/choreo/customer-support/.

        "},{"location":"references/faq/#q-how-can-i-perform-log-monitoring-or-analytics-for-the-azure-environment","title":"Q: How can I perform log monitoring or analytics for the Azure environment?","text":"

        If you have a log monitoring product or service, such as Azure Monitor, you can use it together with Choreo. Note: The log monitoring tool is not included in the infrastructure cost.

        "},{"location":"references/faq/#q-what-is-the-maximum-request-payload-size-supported-by-choreo","title":"Q: What is the maximum request payload size supported by Choreo?","text":"

        Choreo allows a maximum request payload size of 10 MB.

        "},{"location":"references/faq/#q-what-source-control-software-does-choreo-support","title":"Q: What source control software does Choreo support?","text":"

        Choreo now supports GitHub, Bitbucket and GitLab.

        "},{"location":"references/faq/#q-why-dont-i-see-the-undeployed-builds-for-my-component-in-choreo","title":"Q: Why don't I see the undeployed builds for my component in Choreo?","text":"

        You are allowed to build your component any number of times. However, Choreo has a limit on retaining undeployed builds. For users on the free-tier, Choreo will retain only one undeployed build. For those on any other tier, Choreo will retain the latest five undeployed builds.

        "},{"location":"references/faq/#q-what-is-ballerina","title":"Q: What is Ballerina?","text":"

        Ballerina is an open-source programming language designed for the cloud. It simplifies the process of using, combining, and creating network services. When you use Ballerina to write integrations in Choreo, you can save time and deliver 2-3x faster. To learn more, check out https://ballerina.io/.

        "},{"location":"references/faq/#q-what-is-asgardeo","title":"Q: What is Asgardeo?","text":"

        Asgardeo is an identity provider (IdP) that allows developers to secure access for consumers, business partners, employees, and APIs. Asgardeo is Choreo\u2019s default IDP. To learn more, visit https://wso2.com/asgardeo/.

        "},{"location":"references/faq/#q-why-dont-i-see-the-region-selector-on-the-project-creation-page","title":"Q: Why don\u2019t I see the region selector on the project creation page?","text":"

        If you are a Choreo cloud data plane user, you can create projects in multiple regions only if you have a paid subscription in Choreo. Otherwise, your projects will be created in the same region you selected when onboarding the organization.

        If you are a private data plane user, there will be no region selector in project creation at all.

        "},{"location":"references/faq/#q-as-a-cloud-data-plane-user-how-can-i-create-components-in-multiple-data-planes","title":"Q: As a Cloud Data Plane user, how can I create components in multiple data planes?","text":"

        When an organization admin onboards a new organization in Choreo, they can choose the preferred data plane. Choreo then sets the selected data plane as the default for the entire organization. Subsequently, users within the free tier of the cloud data plane can create components only in the set default data plane. If a free-tier user needs to create components in a different data plane, the user must get a paid subscription.

        "},{"location":"references/faq/#security-and-data-protection","title":"Security and data protection","text":""},{"location":"references/faq/#q-how-is-data-managed-in-choreo","title":"Q: How is data managed in Choreo?","text":"

        Choreo manages data using WSO2 containers and Kubernetes clusters, which provide scalability, resilience, and security. Find out more here.

        "},{"location":"references/faq/#q-what-is-the-wso2-subprocessor-list","title":"Q: What is the WSO2 Subprocessor list?","text":"

        This is a detailed list of all subprocessors used by WSO2, including their name, location, and purpose. This information is updated frequently to ensure compliance with data protection regulations and is found here.

        "},{"location":"references/faq/#q-how-do-we-secure-wso2-private-and-public-clouds","title":"Q: How do we secure WSO2 Private and Public Clouds?","text":"

        WSO2 uses a range of security controls and design patterns to protect against several threats, including internal attacks, software supply chain attacks, service and platform attacks, and more. Find out more regarding this here.

        "},{"location":"references/faq/#q-how-can-i-connect-a-choreo-component-with-a-protected-third-party-application","title":"Q: How can I connect a Choreo component with a protected third-party application?","text":"

        To connect a Choreo component with a third-party application, it is necessary to establish seamless communication between the component and the protected third-party application, especially when connecting to external databases like MySQL, MSSQL, PGSQL, Oracle DB, etc. To ensure this, the requests coming from the Choreo data plane must be allowed by adding the specific data plane IP ranges to your allowlist.

        • If your component is deployed in the Choreo US data plane, add the following IP range to your allowlist:

          • 20.22.170.144/28

        • If your component is deployed in the Choreo EU data plane, add the following IP range to your allowlist:

          • 20.166.183.112/28

        • If you are working on the Cybertruck Challenge, add the following IP range to your allowlist:

          • 20.190.30.48/28
        "},{"location":"references/faq/#data-planes","title":"Data planes","text":""},{"location":"references/faq/#q-what-is-a-choreo-control-plane","title":"Q: What is a Choreo control plane?","text":"

        The Choreo control plane is a centralized management component that oversees and coordinates the workloads deployed by customers. It provides a unified point of control and visibility for the organization, allowing administrators to manage, monitor, and orchestrate the organization\u2019s resources efficiently.

        "},{"location":"references/faq/#q-what-is-a-data-plane","title":"Q: What is a data plane?","text":"

        A data plane in Choreo is a computing environment designed for running customer workloads. These environments are hosted in either a dedicated cloud infrastructure owned by the customer (private data planes) or on public cloud infrastructure owned by WSO2, also known as the Choreo data plane.

        "},{"location":"references/faq/#q-which-regions-support-the-choreo-data-planecdp","title":"Q: Which regions support the Choreo data plane(CDP)?","text":"

        The Choreo data plane is currently supported in the US East 2 and North Europe. However, WSO2 is planning to add support for additional regions as needed.

        "},{"location":"references/faq/#q-which-regions-support-private-data-planespdps","title":"Q: Which regions support private data planes(PDPs)?","text":"

        Private data planes can be deployed in any region where Azure and AWS are available and meet the requirements for PDPs.

        "},{"location":"references/faq/#q-if-i-want-to-use-my-azure-aks-instances-as-the-private-data-plane-what-are-the-minimum-requirements-i-should-meet","title":"Q: If I want to use my Azure AKS instances as the private data plane, what are the minimum requirements I should meet?","text":"

        We recommend using a minimum of two (2) workload nodes to ensure high availability.

        "},{"location":"references/faq/#q-are-the-choreo-control-plane-and-data-planes-highly-available-are-they-running-on-multiple-clusters","title":"Q: Are the Choreo control plane and data planes highly available? Are they running on multiple clusters?","text":"

        The Choreo control plane and data plane are designed for high availability using Azure components like AKS, MSSQL, ACR, KV, Service Bus, and so on, with a high availability of 99.99%, which allows at least three workload nodes. In the event of a node failure or upgrade, this setup provides reliable failover. WSO2 also has a backup and recovery strategy in place, including continuous restore drills. If you require AKS cluster-level redundancy, we can consider multiple zones. In this case, the cost will include an additional infrastructure cost.

        "},{"location":"references/faq/#environments","title":"Environments","text":""},{"location":"references/faq/#q-as-a-choreo-cloud-data-plane-user-why-cant-i-create-environments","title":"Q: As a Choreo cloud data plane user, why can't I create environments?","text":"

        You can create environments only if you have a paid subscription in Choreo. It can be either Pay-as-you-Go (PAYG) or an Enterprise plan.

        "},{"location":"references/faq/#q-i-am-a-pay-as-you-go-payg-customer-using-the-choreo-cloud-data-plane-how-many-environments-can-i-create","title":"Q: I am a Pay-As-You-Go (PAYG) customer using the Choreo cloud data plane. How many environments can I create?","text":"

        You can create up to 5 environments at the organization level, including the existing Development & Production environments by default. If you have projects in both data planes (US & EU), there will be 4 environments already created in total, and you will only be allowed to create one additional environment either in the US or EU data plane.

        "},{"location":"references/faq/#q-i-am-an-enterprise-subscription-customer-using-the-choreo-private-data-plane-how-many-environments-do-i-get","title":"Q: I am an Enterprise subscription customer using the Choreo private data plane. How many environments do I get?","text":"

        As an Enterprise subscription customer, the number of environments you can use is not limited. However, the more environments you use, the more resources you will consume in the data plane for the workload you deploy. This may result in higher infrastructure costs for the private data plane.

        "},{"location":"references/faq/#q-as-a-choreo-cloud-data-plane-user-why-dont-i-see-both-us-eu-data-planes-in-the-data-plane-selector-when-creating-an-environment","title":"Q: As a Choreo cloud data plane user, why don\u2019t I see both US & EU data planes in the data plane selector when creating an environment?","text":"

        You will see both US & EU data planes only if you have a paid subscription and have created projects in both US & EU data planes.

        "},{"location":"references/faq/#q-i-am-a-customer-who-use-choreo-in-a-private-data-plane-how-many-environments-can-i-create","title":"Q: I am a customer who use Choreo in a private data plane. How many environments can I create?","text":"

        Initially, you will receive the requested number of environments when establishing your private data plane. Subsequently, you can create additional environments as needed.

        "},{"location":"references/faq/#billing-and-support","title":"Billing and support","text":""},{"location":"references/faq/#q-whom-do-i-reach-out-to-if-i-have-a-billing-question","title":"Q: Whom do I reach out to if I have a billing question?","text":"

        You can reach out to cloud-billing-support@wso2.com or create a support ticket via our support portal.

        "},{"location":"references/faq/#q-whats-a-developer-plan","title":"Q: What's a Developer plan?","text":"

        A Developer plan allows you to try out Choreo\u2019s capabilities at no cost. It\u2019s ideal for proof of concept (PoC) tasks or workloads with limited transactions. This plan allows you to experiment with up to 5 components and provides US$1,000/year of Choreo data plane (CDP) credits.

        "},{"location":"references/faq/#q-how-do-i-calculate-the-infrastructure-costs","title":"Q: How do I calculate the infrastructure costs?","text":"

        Calculating infrastructure costs depends on the type of workload you want to manage. Here are a few examples:

        • Example 1: Managing existing APIs as an API proxy with simple mediation; no additional infrastructure costs.
        • Example 2: Managing existing APIs as an API proxy with complex mediation and policies; Choreo will deploy 1 x container to handle these mediation and policies at approximately US$57.25 per month per API.
        • Example 3: Creating, deploying, and managing a new API or integration within Choreo; pay for 1 x component + infrastructure cost. Each container deployed will be approximately US$57.25 per month on the default configuration provided by Choreo. Additional resources will be charged based on the type of resource required.
        • Example 4: Creating, deploying, and managing a microservice; the same approach as example 3.
        "},{"location":"references/faq/#q-what-are-the-component-limitations","title":"Q: What are the component limitations?","text":"
        • Developer plan: Allows up to a maximum of five free components and unlimited paid components.
        • PAYG plan: Allows unlimited paid components.
        • Enterprise plan: Allows unlimited paid components.
        "},{"location":"references/faq/#q-how-do-i-read-the-bill","title":"Q: How do I read the bill?","text":"

        Your bill will detail the number of components used, infrastructure consumed, support plans used, and any additional services you may have purchased. If you are unsure about any charges on your bill, reach out to choreo-support@wso2.com for clarification.

        "},{"location":"references/faq/#q-is-support-included-in-the-choreo-enterprise-plan","title":"Q: Is support included in the Choreo Enterprise plan?","text":"

        The Choreo Enterprise plan does not automatically include support; however, you can purchase support plans in addition to the Enterprise plan at any time. Find out more at https://wso2.com/choreo/customer-support/.

        "},{"location":"references/faq/#q-i-am-an-enterprise-subscription-customer-who-wants-to-use-the-choreo-private-data-plane-what-costs-will-i-incur-in-addition-to-the-subscription-and-support-plan","title":"Q: I am an Enterprise subscription customer who wants to use the Choreo private data plane. What costs will I incur in addition to the subscription and support plan?","text":"

        You can start by using a basic plan or contact us for an Enterprise support plan.

        "},{"location":"references/faq/#q-i-want-to-upgrade-from-payg-to-an-enterprise-subscription-will-there-be-an-outage-during-the-upgrade","title":"Q: I want to upgrade from PAYG to an Enterprise subscription. Will there be an outage during the upgrade?","text":"

        No, there are no outages when upgrading a plan.

        "},{"location":"references/faq/#choreo-cli","title":"Choreo CLI","text":""},{"location":"references/faq/#q-how-do-i-uninstall-the-cli","title":"Q: How do I uninstall the CLI?","text":"

        If you didn't download the binary directly, you can uninstall the CLI by deleting the .choreo directory in the home directory of your operating system.

        "},{"location":"references/faq/#q-how-do-i-update-the-cli","title":"Q: How do I update the CLI?","text":"

        You can update the CLI by running the following command: 

        curl -o- https://cli.choreo.dev/install.sh | bash\n

        "},{"location":"references/faq/#q-what-are-the-supported-component-types-in-the-cli","title":"Q: What are the supported component types in the CLI?","text":"

        The Choreo CLI currently supports the following component types: - Service - Web Application - Webhook - Scheduled Task - Manual Task

        "},{"location":"references/faq/#q-how-do-i-get-help-with-a-specific-command-in-the-cli","title":"Q: How do I get help with a specific command in the CLI?","text":"

        You can get help with a specific command by running the following command: 

        choreo <command> --help\n

        "},{"location":"references/faq/#q-what-are-the-build-configurations-required-when-creating-components-using-the-cli","title":"Q: What are the build configurations required when creating components using the CLI?","text":"

        You can configure the component build configurations depending on the component type as follows:

        choreo create component <name> --project <name> --build-configs='key1=value1,key2=value2'\nchoreo create component <name> --project <name> --build-configs='key1=value1' --build-configs='key2=value2'\n

        The build configurations required for existing buildpacks are as follows:

        Component Type Buildpack Required Configurations Service Python
        • buildPackLangVersion: Language Version
        Node.js
        • buildPackLangVersion: Language Version
        Java
        • buildPackLangVersion: Language Version
        Go
        • buildPackLangVersion: Language Version
        PHP
        • buildPackLangVersion: Language Version
        Ruby
        • buildPackLangVersion: Language Version
        Docker
        • dockerFilePath: Path to the docker file
        Ballerina
        • Not Applicable
            • WSO2 MI
            • Not Applicable
                • .Net
                • buildPackLangVersion: Language Version
                    • Webapp Python
                    • buildPackLangVersion: Language Version
                    • port: Port
                    Node.js
                    • buildPackLangVersion: Language Version
                    • port: Port
                    Go
                    • buildPackLangVersion: Language Version
                    • port: Port
                    PHP
                    • buildPackLangVersion: Language Version
                    • port: Port
                    Ruby
                    • buildPackLangVersion: Language Version
                    • port: Port
                    .Net
                    • buildPackLangVersion: Language Version
                    • port: Port
                    Docker
                    • dockerFilePath: Path to the docker file
                    • port: Port
                    Static website
                    • Not Applicable
                        • React
                        • buildCommand: Command to be used for building the component
                        • outputDirectory: Output directory for the component build artifacts
                        • nodeVersion: Node.js version used
                        Angular
                        • buildCommand: Command to be used for building the component
                        • outputDirectory: Output directory for the component build artifacts
                        • nodeVersion: Node.js version used
                        Vue
                        • buildCommand: Command to be used for building the component
                        • outputDirectory: Output directory for the component build artifacts
                        • nodeVersion: Node.js version used
                        Webhook Python
                        • buildPackLangVersion: Language Version
                        Node.js
                        • buildPackLangVersion: Language Version
                        Java
                        • buildPackLangVersion: Language Version
                        Go
                        • buildPackLangVersion: Language Version
                        PHP
                        • buildPackLangVersion: Language Version
                        Ruby
                        • buildPackLangVersion: Language Version
                        Docker
                        • dockerFilePath: Path to the docker file
                        Ballerina
                        • Not Applicable
                            • WSO2 MI
                            • Not Applicable
                                • Scheduled Task Python
                                • buildPackLangVersion: Language Version
                                Node.js
                                • buildPackLangVersion: Language Version
                                Java
                                • buildPackLangVersion: Language Version
                                Go
                                • buildPackLangVersion: Language Version
                                .Net
                                • buildPackLangVersion: Language Version
                                PHP
                                • buildPackLangVersion: Language Version
                                Ruby
                                • buildPackLangVersion: Language Version
                                Docker
                                • dockerFilePath: Path to the docker file
                                Ballerina
                                • Not Applicable
                                    • WSO2 MI
                                    • Not Applicable
                                        • Manual Task Python
                                        • buildPackLangVersion: Language Version
                                        Node.JS
                                        • buildPackLangVersion: Language Version
                                        Java
                                        • buildPackLangVersion: Language Version
                                        Go
                                        • buildPackLangVersion: Language Version
                                        .Net
                                        • buildPackLangVersion: Language Version
                                        PHP
                                        • buildPackLangVersion: Language Version
                                        Ruby
                                        • buildPackLangVersion: Language Version
                                        Docker
                                        • dockerFilePath: Path to the docker file
                                        Ballerina
                                        • Not Applicable
                                            • WSO2 MI
                                            • Not Applicable
                                                • "},{"location":"references/private-data-plane-management-models/","title":"Private Data Plane Management Models","text":"

                                                Choreo supports various management models for private data planes (PDPs), fostering collaboration between WSO2 and customers across diverse scenarios. The following sections provide insights into WSO2's fully managed solutions and shared responsibility models, allowing you to make informed decisions regarding cloud-based operations and security.

                                                "},{"location":"references/private-data-plane-management-models/#wso2-fully-managed-infrastructure-and-pdp-in-wso2-subscription-model","title":"WSO2 fully managed (infrastructure and PDP in WSO2 subscription) model","text":"

                                                WSO2 fully managed private data planes are supported only on Azure, AWS, and GCP cloud providers.

                                                Task Task description Responsible party Accountable Consulted Informed Subscription prerequisites - Create subscriptions - Check quota and service limits - Run the Choreo compatibility prerequisite script WSO2 WSO2 Customer (If required) Customer (If required) Remote access for installation Provide owner access WSO2 WSO2 WSO2 WSO2 Network management - Obtain customers backend CIDR in case of VPN/peering - Check end-to-end connectivity (primary and failover) WSO2/Customer WSO2/Customer Customer Customer Firewall rules/access control Set up firewall and required rules depending on the security tier WSO2 WSO2 Customer Customer Infrastructure provisioning - Provision Bastion - Provision Kubernetes clusters WSO2 WSO2 - Customer(If required) Kubernetes cluster management - Manage Kubernetes versions - Increase node pool size WSO2 WSO2 Customer Customer Infrastructure monitoring Set up alerts WSO2 WSO2 - Customer(If required) DNS management for Choreo system - Manage DNS infrastructure - Manage SSL certificates for Choreo system components WSO2/Customer WSO2/Customer Customer Customer Choreo system components deployment Set up PDP agents via Helm WSO2 WSO2 - - Choreo system components management Upgrade/patch/debug versions WSO2 WSO2 - Customer(If required) Choreo system components monitoring - Set up continuous monitoring 24x7 - Provide monthly uptime reports WSO2 WSO2 - Customer Choreo system security monitoring If basic tier - CSPM - Apply security patches - Manage supply chain security (Image scanning, SAST) - Manage security incidents If standard tier/premium tier - CSPM - Apply security patches - Manage supply chain security - Monitor runtime security alerts (Azure Defender) - Monitor security incident and event management (SIEM) alerts - Manage security incidents - Adhere to compliance standards WSO2/Customer WSO2/Customer WSO2/Customer WSO2/Customer Choreo application creation/deployment Customer Customer Customer Customer Choreo application management Customer Customer Customer Customer Choreo application monitoring Customer Customer Customer Customer Choreo application logs Customer Customer Customer Customer"},{"location":"references/private-data-plane-management-models/#wso2-fully-managed-infrastructure-and-pdp-in-customer-subscription-model","title":"WSO2 fully managed (infrastructure and PDP in customer subscription) model","text":"Task Task description Responsible party Accountable Consulted Informed Subscription prerequisites - Create subscriptions - Check quota and service limits - Run the Choreo compatibility prerequisite script Customer Customer WSO2 - Remote access for installation Provide access Customer Customer WSO2 WSO2 Network management - Obtain customers backend CIDR in case of VPN/peering - Check end-to-end connectivity (primary and failover) WSO2/Customer WSO2/Customer Customer Customer Firewall rules/access control Set up firewall and required rules depending on the security tier WSO2/Customer WSO2/Customer Customer Customer Infrastructure provisioning - Provision Bastion - Provision Kubernetes clusters WSO2 WSO2 Customer Customer Kubernetes cluster management - Manage Kubernetes versions - Increase node pool size WSO2 WSO2 Customer Customer Infrastructure monitoring Set up alerts WSO2 WSO2 - Customer(If required) DNS management for Choreo system - Manage DNS infrastructure - Manage SSL certificates for Choreo system components WSO2/Customer WSO2/Customer Customer Customer Choreo system components deployment Set up PDP agents via Helm WSO2 WSO2 Customer - Choreo system components management Upgrade/patch/debug versions WSO2 WSO2 - Customer(If required) Choreo system components monitoring - Set up continuous monitoring 24x7 - Provide monthly uptime reports WSO2 WSO2 - Customer Choreo system security monitoring If basic tier - CSPM - Apply security patches - Manage supply chain security (Image scanning, SAST) - Manage security incidents If standard tier/premium tier - CSPM - Apply security patches - Manage supply chain security - Monitor runtime security alerts (Azure Defender) - Monitor security incident and event management (SIEM) alerts - Manage security incidents - Adhere to compliance standards WSO2/Customer WSO2/Customer WSO2/Customer WSO2/Customer Choreo application creation/deployment Customer Customer Customer Customer Choreo application management Customer Customer Customer Customer Choreo application monitoring Customer Customer Customer Customer Choreo application logs Customer Customer Customer Customer"},{"location":"references/private-data-plane-management-models/#customer-self-managed-wso2-provides-installation-script-and-updates-model","title":"Customer self-managed (WSO2 provides installation script and updates) model","text":"Task Task description Responsible party Accountable Consulted Informed Subscription prerequisites - Create subscriptions - Check quota and service limits - Run the Choreo compatibility prerequisite script Customer Customer WSO2 WSO2 Remote access for installation Provide owner access Customer Customer WSO2 - Network management - Obtain customers backend CIDR in case of VPN/peering - Check end-to-end connectivity (primary and failover) Customer Customer WSO2 WSO2 Firewall rules/access control Set up firewall and required rules depending on the security tier Customer Customer WSO2 WSO2 Infrastructure provisioning - Provision Bastion - Provision Kubernetes clusters Customer Customer WSO2 WSO2(If required) Kubernetes cluster management - Manage Kubernetes versions - Increase node pool size Customer Customer WSO2 WSO2(If required) Infrastructure monitoring Set up alerts Customer Customer WSO2 - DNS management for Choreo system - Manage DNS infrastructure - Manage SSL certificates for Choreo system components Customer Customer WSO2 - Choreo system components deployment Set up PDP agents via Helm Customer Customer WSO2 - Choreo system components management Upgrade/patch/debug versions Customer Customer WSO2 - Choreo system components monitoring - Set up continuous monitoring 24x7 - Provide monthly uptime reports Customer Customer WSO2 - Choreo system security monitoring If basic tier - CSPM - Apply security patches - Manage supply chain security (Image scanning, SAST) - Manage security incidents If standard tier/premium tier - CSPM - Apply security patches - Manage supply chain security - Monitor runtime security alerts (Azure Defender) - Monitor security incident and event management (SIEM) alerts - Manage security incidents - Adhere to compliance standards WSO2/Customer WSO2/Customer WSO2/Customer WSO2/Customer Choreo application creation/deployment Customer Customer Customer Customer Choreo application management Customer Customer Customer Customer Choreo application monitoring Customer Customer Customer Customer Choreo application logs Customer Customer Customer Customer"},{"location":"references/private-data-plane-security-levels/","title":"Private Data Plane Security Levels","text":"

                                                The following table outlines the private data plane security levels supported in Choreo:

                                                Basic tier Standard tier Premium tier Distributed denial-of-service (DDoS) protection basic * Distributed denial-of-service (DDoS) protection basic * Distributed denial-of-service (DDoS) protection premium * Controlled admin access * Controlled admin access * Controlled admin access * End-to-end data encryption in transit End-to-end data encryption in transit End-to-end data encryption in transit Data encryption at rest * Data encryption at rest * Data encryption at rest * Secret management Secret management Secret management Foundational CSPM * Foundational CSPM * Premium CSPM * Static application security testing (SAST) Static application security testing (SAST) Static application security testing (SAST) Infrastructure as code (IaC) scanning Infrastructure as code (IaC) scanning Infrastructure as code (IaC) scanning Software composition analysis Software composition analysis Software composition analysis Docker image security scanning Docker image security scanning Docker image security scanning N/A Kubernetes runtime protection * Kubernetes runtime protection * N/A Web application firewall (WAF) * Web application firewall (WAF) * N/A N/A Network firewall *

                                                * Not available in the on-premises private data plane.

                                                Tip

                                                Available add-ons: - Security incident and event management (SIEM). - 24/7 security operation center.

                                                "},{"location":"references/troubleshoot-choreo/","title":"Troubleshoot Choreo","text":"

                                                This page walks you through common problems you may encounter when building and deploying components with Choreo, along with the recommended solutions to resolve each issue.

                                                "},{"location":"references/troubleshoot-choreo/#troubleshoot-component-build-errors","title":"Troubleshoot component build errors","text":""},{"location":"references/troubleshoot-choreo/#deploying-an-angular-web-application-displays-the-nginx-welcome-page-instead-of-the-applications-homepage","title":"Deploying an Angular web application displays the Nginx welcome page instead of the application's homepage.","text":"

                                                This occurs due to specifying an incorrect build output directory when you set up your Angular application in Choreo. To resolve the issue, follow the guidelines given below:

                                                • Ensure that the build output directory correctly points to where your Angular build script outputs the files. The deafult output directory is dist/<project-name>.
                                                • Make sure to reconfigure the build settings if the current configuration is incorrect.
                                                "},{"location":"references/troubleshoot-choreo/#an-error-occurs-in-the-container-trivy-scan-when-building-a-byoc-component","title":"An error occurs in the container Trivy scan when building a BYOC component.","text":"

                                                The recommended approach to address this issue is to fix the identified vulnerability and rebuild the component.

                                                However, if you want to add a .trivyignore file to overcome the issue, ensure to add it to the Docker build context path specified when creating the component. For example, {buildContextPath}./trivyignore.

                                                "},{"location":"references/troubleshoot-choreo/#the-configjs-file-is-not-properly-mounted-in-a-web-application","title":"The config.js file is not properly mounted in a web application.","text":"

                                                To resolve this issue, follow the steps given below:

                                                1. Add the config.js file to the app/public directory in your repository.

                                                2. Reference it from the index.html file by adding a script tag as follows:

                                                  <script src=\"public/config.js\"></script>

                                                "},{"location":"references/troubleshoot-choreo/#troubleshoot-component-deployment-errors","title":"Troubleshoot component deployment errors","text":""},{"location":"references/troubleshoot-choreo/#the-configjs-file-is-not-properly-integrated-during-the-deployment-of-a-react-application-causing-it-to-render-with-unexpected-html-instead-of-the-expected-javascript-configuration","title":"The config.js file is not properly integrated during the deployment of a React application, causing it to render with unexpected HTML instead of the expected JavaScript configuration.","text":"

                                                To ensure correct loading of the config.js file, follow the steps given below:

                                                • Reference the config.js file from the index.html file of your application by adding a script tag as follows:

                                                  <script src=\"public/config.js\"></script>

                                                • Verify that the path in the script tag matches the location where the config.js file is stored in your repository.

                                                • Make sure the script tag is placed within the <body> tag in your index.html file. You must ensure that it is not mistakenly placed within another HTML element.
                                                "},{"location":"references/troubleshoot-choreo/#im-not-aware-of-the-commits-that-can-trigger-an-automatic-build-in-choreo","title":"I'm not aware of the commits that can trigger an automatic build in Choreo.","text":"

                                                Merge commits and commits pushed directly to the branch can trigger a build in Choreo.

                                                "},{"location":"references/troubleshoot-choreo/#troubleshoot-web-application-issues","title":"Troubleshoot web application issues","text":""},{"location":"references/troubleshoot-choreo/#after-building-a-web-application-the-nginx-welcome-page-is-displayed-instead-of-the-web-application-home-page","title":"After building a web application, the Nginx welcome page is displayed instead of the web application home page.","text":"

                                                This can happen if an incorrect build output directory is specified during component creation.

                                                During the build process, output files including the index.html are copied to the Nginx root directory. To ensure that the correct files are copied during the build process, you must check the Docker build logs.

                                                "},{"location":"references/troubleshoot-choreo/#the-language-i-prefer-to-use-is-not-available-as-a-buildpack","title":"The language I prefer to use is not available as a buildpack.","text":"

                                                In such scenarios, you can use the Dockerfile buildpack to create the component.

                                                "},{"location":"references/troubleshoot-choreo/#i-mistakenly-used-an-incorrect-build-command-when-creating-a-web-application-how-can-i-update-it-before-triggering-a-build","title":"I mistakenly used an incorrect build command when creating a web application. How can I update it before triggering a build?","text":"

                                                You can go to the build page of the component and update the build command in the build configurations section.

                                                "},{"location":"references/troubleshoot-choreo/#troubleshoot-managed-authentication-issues","title":"Troubleshoot managed-authentication issues","text":""},{"location":"references/troubleshoot-choreo/#after-securing-a-web-application-with-managed-authentication-im-not-able-to-add-users-who-can-sign-in-to-the-application","title":"After securing a web application with managed authentication, I\u2019m not able to add users who can sign in to the application.","text":"

                                                For step-by-step instructions on how to manage users with Choreo's built-in identity provider (IdP), see Configure a User Store with the Built-In IdP.

                                                For details on setting up other OpenID Connect (OIDC) supported IdPs, see Manage OAuth Keys.

                                                "},{"location":"references/troubleshoot-choreo/#troubleshoot-tailscale-proxy-issues","title":"Troubleshoot Tailscale proxy issues","text":""},{"location":"references/troubleshoot-choreo/#where-can-i-find-logs-to-troubleshoot-tailscale-proxy-issues","title":"Where can I find logs to troubleshoot Tailscale proxy issues?","text":"

                                                To troubleshoot Tailscale proxy issues, you can view the Runtime Logs of the running container for your Tailscale proxy deployment. These logs can help you diagnose most of the issues. You can also view real-time container logs via the Runtime page under DevOps. For more details, see Observe real-time container logs.

                                                "},{"location":"references/troubleshoot-choreo/#im-not-able-to-connect-the-tailscale-proxy-node-to-my-tailscale-network-due-to-an-authentication-failure","title":"I'm not able to connect the Tailscale proxy node to my Tailscale network due to an authentication failure.","text":"

                                                • If you encounter the following log lines in your Tailscale proxy deployment, it indicates a misconfiguration of the TS_AUTH_KEY:

                                                  2024-06-04T10:38:53.885800940Z To authenticate, visit:\n2024-06-04T10:38:53.885802684Z \n2024-06-04T10:38:53.885815708Z https://login.tailscale.com/a/696841f011517\n2024-06-04T10:38:53.885817457Z \n2024-06-04T10:38:55.194344862Z Waiting for tailscale up to complete...\n2024-06-04T10:38:57.198970796Z Waiting for tailscale up to complete...\n2024-06-04T10:38:59.203265659Z Waiting for tailscale up to complete...\n
                                                  To resolve this, you must re-check your authentication key and ensure you have entered the correct key.

                                                • If you encounter the following log lines in your Tailscale proxy deployment, it indicates that your authentication key is invalid or expired. 

                                                  2024-06-04T11:33:58.762363181Z 2024/06/04 11:33:58 Received error: invalid key: unable to validate API key\n2024-06-04T11:33:58.762458209Z backend error: invalid key: unable to validate API key\n

                                                  To resolve this, you must verify the correctness of your authentication key. If the key has expired, you must generate a new key from Tailscale admin console.

                                                "},{"location":"references/troubleshoot-choreo/#im-not-able-to-access-private-endpoints-although-the-tailscale-proxy-is-properly-connected-to-my-tailscale-network","title":"I'm not able to access private endpoints although the Tailscale proxy is properly connected to my Tailscale network.","text":"

                                                To resolve this, do the following:

                                                • Ensure your on-premises setup is properly connected to the Tailscale network and that specific services, database servers, etc., are running as expected in your on-premises setup.
                                                • Verify that the IP addresses and ports specified in your Config.yaml file (mounted to Tailscale proxy during deployment) match the IP addresses in your Tailscale network.
                                                • Cross-check the ports defined in the endpoints.yaml file with the port mappings in the Config.yaml file.
                                                "},{"location":"testing/test-apis-with-choreo-apichat/","title":"Test APIs with Choreo API Chat","text":"

                                                Testing APIs is an essential step in the API development process. Choreo simplifies the testing task by allowing you to engage with your APIs using natural language through Choreo API Chat. It eliminates manual test scenario creation and JSON payload accuracy concerns. It enables easy API communication using human language and requires no coding for handling sequences with multiple resource calls. This makes your API testing efficient and user-friendly.

                                                Info

                                                This feature is available for REST API Proxy components and Service components with REST endpoints.

                                                "},{"location":"testing/test-apis-with-choreo-apichat/#prerequisites","title":"Prerequisites","text":"

                                                Before you try out this guide, be sure that you have the following:

                                                • A REST API Proxy component or a Service component that exposes a REST API with a valid OpenAPI specification.

                                                  Info

                                                  • If you are creating a REST API Proxy component, you can create it either by using a valid OpenAPI specification or by defining the resources manually.
                                                  • If you are creating a service component with the Dockerfile preset, make sure to expose the OpenAPI specification from your component.
                                                  • If you do not already have a component, you can choose to create one from the following sources:
                                                  Component type Sample source Reference documentation REST API Proxy https://raw.githubusercontent.com/wso2/choreo-sample-apps/main/rest-api-proxy/pet-store/openapi.yaml Develop an API Proxy Service (Exposing a REST API endpoint) https://github.com/wso2/choreo-sample-apps/tree/main/java/pet-store Develop a Service
                                                "},{"location":"testing/test-apis-with-choreo-apichat/#test-your-apis","title":"Test your APIs","text":"

                                                Follow the steps below to test an API with API Chat:

                                                1. Sign in to the Choreo Console.
                                                2. In the Component Listing pane, click on the component you want to test.
                                                3. On the left navigation, click Test and then click API Chat. This opens the API Chat pane.
                                                4. You can enter your query in natural language and execute it. For example, if you have a resource like \"/pet/findByStatus,\" you can input the query, such as \"Get the pets that are available,\" and execute it to obtain results. The resources are executed sequentially based on your query. Alternatively, you can use the sample queries available to try out API Chat.
                                                "},{"location":"testing/test-apis-with-curl/","title":"Test APIs with cURL","text":"

                                                Testing APIs is an essential step in the API development process. Choreo simplifies the testing task by allowing you to use cURL commands generated by Choreo.

                                                You can follow the steps below to generate a cURL command and test your API method:

                                                1. Sign in to the Choreo Console.

                                                2. In the Component Listing pane, click on the component you want to test.

                                                3. Click Test in the left navigation menu and then click cURL. This opens the cURL pane.

                                                4. In the cURL pane, select the environment from the drop-down list.

                                                5. Select an appropriate HTTP method from the Method list.

                                                6. Click the Parameters tab and add the necessary parameters for the API method.

                                                7. Click the Headers tab and add the required header values.

                                                8. Click the Body tab and select the message body type to invoke the API method.

                                                9. Copy the generated cURL command.

                                                10. Use the copied cURL command via a cURL client to test your API method.

                                                "},{"location":"testing/test-components-with-test-runner/","title":"Test Components with Test Runner","text":"

                                                Test Runner is a component type in Choreo that simplifies the process of running automated tests against your components deployed in Choreo. This capability helps developers evaluate applications in different setups and environments, leading to more confidence and improved visibility into the application's status.

                                                You can create tests using popular programming languages like Go, Java, JavaScript, Python, and more. Additionally, you have the option to build a test runner component by supplying a Dockerfile containing a series of test scripts or by offering a set of Postman Collections.

                                                "},{"location":"testing/test-components-with-test-runner/#prerequisites","title":"Prerequisites","text":"

                                                Before you try out the steps in this guide, complete the following:

                                                • If you are signing in to the Choreo Console for the first time, create an organization as follows:
                                                  1. Go to https://console.choreo.dev/, and sign in using your preferred method.
                                                  2. Enter a unique organization name. For example, Stark Industries.
                                                  3. Read and accept the privacy policy and terms of use.
                                                  4. Click Create. This creates the organization and opens the Project Home page of the default project created for you.
                                                • Fork the Choreo examples repository, which contains the test runner sample for this guide.

                                                You can develop tests in a language of your choice and execute them within the Choreo platform.

                                                "},{"location":"testing/test-components-with-test-runner/#create-a-test-runner-component-using-a-buildpack","title":"Create a test runner component using a buildpack","text":"
                                                1. Go to https://console.choreo.dev/ and sign in. This opens the project home page.
                                                2. Click +Create in the Component Listing section.
                                                3. Click the Test Runner card.

                                                4. Enter a display name, unique name, and description for the test runner component. For this guide, enter the following values:

                                                  Info

                                                  In the Component Name field, you must specify a name to uniquely identify the component in various contexts. The value is editable only at the time you create the component. You cannot change the name after you create the component.

                                                  Field Value Component Display Name Go Test Runner Component Name go-test-runner Description Test Runner implemented in Go

                                                5. Go to the GitHub tab.

                                                6. To allow Choreo to connect to your GitHub account, click Authorize with GitHub. If you have not already connected your GitHub repository to Choreo, enter your GitHub credentials and select the repository you created in the prerequisites section to install the Choreo GitHub App.

                                                  Alternatively, you can paste the Choreo samples repository URL in the Provide Repository URL field to connect to it without requiring authorization from the Choreo Apps GitHub application. However, authorizing the repository with the Choreo GitHub App is necessary if you want to enable Auto Deploy for the component.

                                                  Note

                                                  The Choreo GitHub App requires the following permissions:

                                                  • Read and write access to code and pull requests.
                                                  • Read access to issues and metadata.

                                                  You can revoke access if you do not want Choreo to have access to your GitHub account. However, write access is exclusively utilized for sending pull requests to a user repository. Choreo will not directly push any changes to a repository.

                                                7. Under Connect Your Repository, enter the following information:

                                                  Field Value Organization Your GitHub account GitHub Repository choreo-samples Branch main

                                                8. Under Buildpack, select a buildpack based on the language of your choice.

                                                9. Based on the buildpack you chose, go to the relevant tab below and enter the respective values for the Project directory and Language version fields:

                                                  GoJavaScriptPythonJavaDockerfilePostman Field Value Go Project Directory /test-runner-go Language Version 1.x Field Value Project Directory /test-runner-javascript Language Version 18.x.x Field Value Project Directory /test-runner-python Language Version 3.10.x Field Value Project Directory /test-runner-java Language Version 17

                                                  For programming languages that doesn't support buildpacks or for advanced use cases, you can define your own Dockerfile and run test workloads. Refer to for more information. Field Value Postman Directory /postman-collection-dir

                                                10. Click Create.

                                                  11. You have successfully created a Test Runner component using a buildpack of your choice. Now let's build and run the tests.

                                                  "},{"location":"testing/test-components-with-test-runner/#build-and-deploy-the-test-runner-component-to-execute-the-tests","title":"Build and deploy the test runner component to execute the tests","text":"
                                                  1. In the left navigation menu, click Build.
                                                  2. In the Builds pane, click Build Latest.
                                                  3. On the left navigation, click Deploy.
                                                  4. In the Set Up card, click Deploy to deploy the test runner component. If you want to provide additional configuration or secrets, use the Configure and Deploy option from the list.
                                                  5. Once the deployment is successful, click Execute in the left navigation menu.
                                                  6. Select the environment from the environment list and click Run Now to trigger a test execution.

                                                  7. Once the execution is completed it is listed on the execution page. This may take some time. Once the execution is listed, you can click on a particular execution to view the test result(s).

                                                    Inject dynamic values into your application as command-line arguments

                                                    If you want to inject dynamic values into your application as command-line arguments when you run a test runner component, follow the steps given below:

                                                    1. Click the drop-down icon next to Run Now and then click Run with Arguments.
                                                    2. In the Runtime Arguments pane that opens, enter the arguments you want to pass to your application.
                                                    3. Click Execute. This triggers the test runner with the specified arguments.

                                                    Tip

                                                    For Postman Collections:

                                                    • The default behavior is to run all the collections in the specified directory.
                                                    • To run specific collections in the directory, use -f or --files as the first argument, followed by a comma-separated list of collections.
                                                    • Since Choreo uses Newman internally to run Postman Collections, you can pass any valid Newman arguments.
                                                  "},{"location":"testing/test-graphql-endpoints-via-the-graphql-console/","title":"Test GraphQL Endpoints via the GraphQL Console","text":"

                                                  Choreo provides an integrated GraphQL Console to test publicly exposed GraphQL endpoints of Service components you create and deploy. The GraphQL Console allows you to write queries and mutations interactively. As Choreo uses OAuth2.0 authentication by default to secure GraphQL APIs, the GraphQL Console generates test keys to test APIs.

                                                  Follow the steps below to test a GraphQL endpoint via the GraphQL Console:

                                                  1. Sign in to the Choreo Console.

                                                  2. In the Component Listing pane, click on the component you want to test.

                                                  3. Click Test in the left navigation menu and then click Console. This opens the GraphQL Console pane.

                                                  4. In the GraphQL Console pane, select the environment from the drop-down list.

                                                  5. Select the required endpoint from the Endpoint list.

                                                    Note

                                                    • The Network Visibility of an endpoint is set in the endpoints.yaml. You can set it to Public, Organization, or Project.
                                                    • If you have set the Network Visibility of the endpoint in the endpoints.yaml to Public, continue with step 7.
                                                    • If you have set the Network Visibility of the endpoint in the endpoints.yaml to Organization, the GraphQL endpoint will not be invokable from outside the organization. In this instance, for testing purposes, Choreo allows you to generate a temporay test URL that will be active for 15 minutes. Execute step 6 to generate the temporary URL.

                                                  6. If the Network Visibility of the endpoint is set to Organization, click on Generate URL to generate a temporary test URL that will be active for 15 minutes. Else, skip this step.

                                                    Note

                                                    The temporay test URL will be available only for 15 minutes and it will get expired after. You can deactivate the test URL by clicking on the Deactivate URL button.

                                                  7. Enter the API path and the query or mutation you want to test.

                                                  8. Click the play icon.

                                                    Tip

                                                    If you want to generate a required query or mutation for testing via the GraphQL Explorer, click Explorer to open the GraphQL Explorer.

                                                    Note

                                                    GraphQL Explorer has a known issue causing improper construction of list inputs. To work around this, you must manually update the list input in the generated query before executing it.

                                                  "},{"location":"testing/test-rest-endpoints-via-the-openapi-console/","title":"Test REST Endpoints via the OpenAPI Console","text":"

                                                  Choreo provides an integrated OpenAPI Console to test REST endpoints of Service components that you create and deploy. As Choreo uses OAuth2.0 authentication to secure REST APIs, the OpenAPI Console generates test keys to test APIs.

                                                  Follow the steps below to test a REST endpoint via the integrated OpenAPI Console:

                                                  1. Sign in to the Choreo Console.

                                                  2. In the Component Listing pane, click on the component you want to test.

                                                  3. Click Test in the left navigation menu and then click Console. This opens the OpenAPI Console pane.

                                                  4. In the OpenAPI Console pane, select the environment from the drop-down list.

                                                  5. Select the required endpoint from the Endpoint list.

                                                    Note

                                                    • The Network Visibility of an endpoint is set in the endpoints.yaml. You can set it to Public, Organization, or Project.
                                                    • If you have set the Network Visibility of the endpoint in the endpoints.yaml to Public, go to step 7.
                                                    • If you have set the Network Visibility of the endpoint in the endpoints.yaml to Organization, the endpoint will not be publicly accessible. However, for testing purposes, Choreo offers the ability to create a temporary test URL that is publicly accessible (secured with OAuth 2.0) and remains active for 15 minutes. To generate the temporary URL, proceed with step 6.

                                                  6. If the Network Visibility of the endpoint is set to Organization, click on Generate URL to generate a temporary test URL that will be active for 15 minutes. Else, skip this step.

                                                    Note

                                                    The temporary test URL will be available only for 15 minutes and it will get expired after. You can deactivate the test URL by clicking on the Deactivate URL button.

                                                  7. Expand the resource you want to test.

                                                  8. Click Try it out.

                                                  9. Enter values for parameters if applicable.

                                                  10. Click Execute. You can see the response body under Responses.

                                                  "},{"location":"tutorials/expose-a-service-as-a-managed-api/","title":"Expose a Service as a Managed API","text":"

                                                  Choreo simplifies securely exposing existing services as managed APIs. It also allows you to effectively manage all aspects of an API's lifecycle, security, throttling, and governance so that you can focus more on service development.

                                                  In this tutorial, you will use Choreo to expose a service as an API proxy and publish it to the Choreo Developer Portal for application developers to consume.

                                                  "},{"location":"tutorials/expose-a-service-as-a-managed-api/#prerequisites","title":"Prerequisites","text":"

                                                  Before you try out this tutorial, complete the following:

                                                  • If you are signing in to the Choreo Console for the first time, create an organization as follows:

                                                    1. Go to https://console.choreo.dev/, and sign in using your preferred method.
                                                    2. Enter a unique organization name. For example, Stark Industries.
                                                    3. Read and accept the privacy policy and terms of use.
                                                    4. Click Create.

                                                    This creates the organization and opens the Project Home page of the default project created for you.

                                                  "},{"location":"tutorials/expose-a-service-as-a-managed-api/#step-1-create-an-api-proxy","title":"Step 1: Create an API proxy","text":"

                                                  To create an API proxy, you can either upload an OpenAPI specification or provide an OpenAPI specification URL. In this tutorial, you will use a URL of a sample OpenAPI specification.

                                                  Follow the steps given below:

                                                  1. Go to https://console.choreo.dev/ and sign in. This opens the project home page.
                                                  2. If you already have one or more components in your project, click + Create under Component Listing. Otherwise, proceed to the next step.
                                                  3. Click the API Proxy card.
                                                  4. In the Create an API Proxy pane that opens, click Try with sample URL.
                                                  5. Click Next.

                                                  6. Update the populated API proxy details with the values given in the following table:

                                                    Info

                                                    In the Name field, you must specify a name to uniquely identify the component in various contexts. The value is editable only at the time you create the component. You cannot change the name after you create the component.

                                                    Field Value Display Name Swagger Petstore Name swagger-petstore Context api/v3 Version 1.0 Target https://petstore3.swagger.io/api/v3 Access Mode External: API is publicly accessible

                                                  7. Click Create. This creates the component and takes you to the Overview page of the component.

                                                  To see the resources of the API proxy, go to the left navigation menu, click Develop, and then click Resources.

                                                  "},{"location":"tutorials/expose-a-service-as-a-managed-api/#step-2-deploy-the-api-proxy","title":"Step 2: Deploy the API proxy","text":"

                                                  To deploy the API proxy to the development environment, follow the steps given below:

                                                  1. In the left navigation menu, click Deploy.

                                                  2. In the Build Area card, click Configure & Deploy. This opens the Configure & Deploy pane, where you can select the API access mode depending on how you want the API to be accessible.

                                                    Here, you can select External to make the API publicly accessible, and then click Deploy.

                                                    Once the deployment is complete, the Development card indicates the Deployment Status as Active.

                                                  Now you are ready to test the API proxy.

                                                  "},{"location":"tutorials/expose-a-service-as-a-managed-api/#step-3-test-the-api-proxy","title":"Step 3: Test the API proxy","text":"

                                                  You can test the API proxy in the development environment before promoting it to production. Choreo provides the following options to test your API proxy: - OpenAPI Console - cURL

                                                  In this guide, you will use the OpenAPI Console.

                                                  To test the API proxy via the OpenAPI Console, follow the steps given below:

                                                  1. In the left navigation menu, click Test and then click OpenAPI Console.

                                                    Tip

                                                    Since the API proxy is secured when it is deployed, you will need a key to invoke it. Choreo automatically generates a key when you navigate to the OpenAPI Console pane.

                                                  2. In the OpenAPI Console pane, select Development from the environment drop-down list.

                                                  3. Expand the GET /pet/findByStatus method and click Try it Out to test it.

                                                  4. Select available as the status and click Execute. You will see a response similar to the following:

                                                  This indicates that your API proxy is working as expected.

                                                  "},{"location":"tutorials/expose-a-service-as-a-managed-api/#step-4-promote-the-api-proxy-to-production","title":"Step 4: Promote the API proxy to production","text":"

                                                  Once you verify that the API proxy is working as expected in the development environment, you can follow the steps given below to promote it to production:

                                                  1. In the left navigation menu, click Deploy.
                                                  2. In the Development card, click Promote.

                                                  3. In the Configure & Deploy pane that opens, click Next.

                                                    Tip

                                                    If you want to specify a different endpoint for your production environment, you can make the change in the Configure & Deploy pane.

                                                  The Production card indicates the Deployment Status as Active when the API proxy is successfully deployed to production.

                                                  If you want to verify that the API proxy is working as expected in production, you can test the API in the production environment.

                                                  Now that your API is deployed in both development and production environments and can be invoked, the next step is to publish it so that consumers can discover and subscribe to it.

                                                  "},{"location":"tutorials/expose-a-service-as-a-managed-api/#step-5-publish-the-api-proxy","title":"Step 5: Publish the API proxy","text":"

                                                  To publish the API to the Choreo Developer Portal, follow the steps given below:

                                                  1. In the left navigation menu, click Manage and then click Lifecycle. This opens the Lifecycle page, where you can see the different lifecycle stages that an API can be in. You can see that the current lifecycle stage is Created.
                                                  2. Click Publish.
                                                  3. In the Publish API dialog that opens, click Confirm to proceed publishing the API with the specified display name. If you want to change the display name, make the necessary changes and then click Confirm. This changes the API lifecycle state to Published.

                                                  You can observe that the API lifecycle stage has changed to Published. Now the API is available for consumption. API consumers can consume the API via the Choreo Developer Portal.

                                                  "},{"location":"tutorials/expose-a-service-as-a-managed-api/#step-6-invoke-the-api","title":"Step 6: Invoke the API","text":"

                                                  To generate credentials for the published API and to invoke it via the Developer Portal, follow the steps below:

                                                  1. In the Lifecycle Management pane, click Go to DevPortal. This takes you to the Petstore API published to the Choreo Developer Portal.

                                                  2. To generate credentials for testing the API, follow the steps given below:

                                                    1. In the Developer Portal left navigation menu, click Production under Credentials.
                                                    2. Click Generate Credentials. Choreo generates new tokens and populates the Consumer Key and Consumer Secret fields.

                                                  3. To invoke the API, follow the steps given below:

                                                    1. In the Developer Portal left navigation menu, click Try Out.
                                                    2. In the Endpoint list, select Development as the environment to try out the API.
                                                    3. Click Get Test Key. This generates an access token.
                                                    4. Expand the GET /pet/findByStatus operation and click Try it out.
                                                    5. Select available as the status and click Execute.

                                                  Now you have successfully created, deployed, tested, and published an API proxy using Choreo.

                                                  "},{"location":"tutorials/secure-an-api-with-role-based-access-control/","title":"Secure an API with Role-Based Access Control","text":"

                                                  Role-based access control is a flexible and scalable approach to manage access to API resources. In this approach, each user or group is assigned a specific role that determines the permission granted to perform operations on an API resource.

                                                  This tutorial explains how to implement role-based access control using Choreo and Asgardeo. It includes a real-world scenario with instructions to create and publish an API proxy component in Choreo and apply role-based access control.

                                                  "},{"location":"tutorials/secure-an-api-with-role-based-access-control/#scenario","title":"Scenario","text":"

                                                  An organization needs to implement a user management service to keep track of users. The service needs to perform the following four operations:

                                                  • List existing users
                                                  • List a user
                                                  • Create new users
                                                  • Delete a user

                                                  There are two types of users in the organization:

                                                  • Human Resource Manager (HR manager)
                                                  • Human Resource Officer (HR officer)

                                                  Each user type requires different levels of access to the user management service.

                                                  • The HR manager must have permission to perform the following operations: list existing users, list a user, create new users, and delete a user.
                                                  • The HR officer must have permission to perform the following operations: list existing users and list a user.
                                                  "},{"location":"tutorials/secure-an-api-with-role-based-access-control/#implement-role-based-access-control-with-choreo-and-asgardeo","title":"Implement role-based access control with Choreo and Asgardeo","text":"

                                                  Let\u2019s take a look at the steps to follow to implement the scenario described above using Choreo and Asgardeo.

                                                  "},{"location":"tutorials/secure-an-api-with-role-based-access-control/#prerequisites","title":"Prerequisites","text":"

                                                  Before you try out this guide, complete the following:

                                                  If you are signing in to the Choreo Console for the first time, create an organization as follows:

                                                  1. Go to https://console.choreo.dev/, and sign in using your preferred method.
                                                  2. Enter a unique organization name. For example, Stark Industries.
                                                  3. Read and accept the privacy policy and terms of use.
                                                  4. Click Create.

                                                  This creates the organization and opens the home page of the default project created for you.

                                                  Enable Asgardeo as the key manager

                                                  If you created your organization in Choreo before the 21st of February 2023, and you have not already enabled Asgardeo as the key manager, follow these steps to enable Asgardeo as the default key manager:

                                                  1. In the Choreo Console, go to the top navigation menu and click Organization. This takes you to the organization's home page.
                                                  2. In the left navigation menu, click Settings.
                                                  3. In the header, click the Organization list. This will open the organization level settings page.
                                                  4. Click the API Management tab and then click Enable Asgardeo Key Manager.

                                                  5. In the confirmation dialog that opens, click Yes.

                                                    Tip

                                                    Enabling Asgardeo as the default key manager has the following effects:

                                                    • Once the Asgardeo Key Manager is enabled, it will act as the default key manager. You cannot disable, change, or remove it.
                                                    • Existing applications created via the Developer Portal in your organization will continue to function as usual. However, any new application you create within the organization will use Asgardeo as the key manager.
                                                    • New grant types such as Password, Authorization Code, PKCE, and Implicit, which were not available in Choreo will become available.
                                                    • The capability to add an external IdP will be disabled because Asgardeo does not support token exchange. However, you can use the federation capabilities of Asgardeo to achieve similar functionality.
                                                  "},{"location":"tutorials/secure-an-api-with-role-based-access-control/#step-1-create-an-api-proxy-component-and-deploy-it","title":"Step 1: Create an API proxy component and deploy it","text":"

                                                  Follow these steps to create an API proxy component, add resources, and deploy it:

                                                  1. Go to https://console.choreo.dev/ and sign in. This opens the project home page.
                                                  2. To create an API proxy component, follow the instructions in Develop an API Proxy: Step 1. This opens the Resources pane, where you can define resources for the API proxy.

                                                  3. In the Resources pane, follow the steps given below to add resources:

                                                    • Select GET as the HTTP Verb, enter /users as the URI Pattern, and click + to add the resource.
                                                    • Select GET as the HTTP Verb, enter /users/{userID} as the URI Pattern, and click + to add the resource.
                                                    • Select POST as the HTTP Verb, enter /users as the URI Pattern, and click + to add the resource.
                                                    • Select DELETE as the HTTP Verb, enter /users/{userID} as the URI Pattern, and click + to add the resource.

                                                  4. To remove the five default resources that start with /*, click the delete icon corresponding to each resource. This marks the resources for deletion.

                                                  5. Click Save. The API resources will be as follows:

                                                  6. In the left navigation menu, click Deploy.

                                                  7. Go to the Build Area card and click Configure & Deploy.
                                                  8. In the Configure API Access Mode pane that opens, select either External or Internal, depending on how you want the API to be accessible. In this tutorial, select External.
                                                  9. Click Deploy.
                                                  "},{"location":"tutorials/secure-an-api-with-role-based-access-control/#step-2-apply-permission-to-resources-and-publish-the-api","title":"Step 2: Apply permission to resources and publish the API","text":"

                                                  Follow these steps:

                                                  1. On the Deploy page, go to the Build Area card and click Security Settings.
                                                  2. In the Security Settings pane, go to the Permissions List section and click + Add Permission(Scope).
                                                  3. To add necessary permission values to the permission list, follow the steps given below:
                                                    1. In the Permissions List section, enter get_user_list as the permission value and click +Add New.
                                                    2. Similarly, add get_user, create_user, and delete_user as permission values.

                                                  4. In the Permissions section, expand each resource and select the permission values as follows for each:

                                                    Resource Permission GET/users get_user_list GET/users/{userID} get_user POST/users create_user DELETE/users/{userID} delete_user

                                                  5. Click Apply.

                                                  6. To apply the latest permissions to the deployed component, you must redeploy it. Follow the steps below to redeploy:
                                                    1. Go to the Build Area card and click Configure & Deploy.
                                                    2. In the Configure API Access Mode pane that opens, select either External or Internal, depending on how you want the API to be accessible. In this tutorial, select External.
                                                    3. Click Deploy.

                                                  Now you are ready to promote the API to production.

                                                  1. In the left navigation menu, click Deploy.
                                                  2. Go to the Development card and click Promote. The Configure & Deploy pane opens with the Use Development endpoint configuration option selected by default.
                                                  3. Click Next to promote the API to production. Now you can publish the API
                                                  4. In the left navigation menu, click Manage and then click Lifecycle.
                                                  5. In the Lifecycle Management pane, click Publish. This changes the status of the API to Published.

                                                  Now, an application developer can discover the API, subscribe to it and then invoke it.

                                                  "},{"location":"tutorials/secure-an-api-with-role-based-access-control/#step-3-subscribe-to-the-published-api","title":"Step 3: Subscribe to the Published API","text":"

                                                  In this step, you take the role of an application developer who consumes the published API. To consume the API, you must create an application, generate keys, and subscribe to the API.

                                                  Follow these steps:

                                                  1. Go to the API Developer Portal and click Applications on the top menu.
                                                  2. Click +Create.
                                                  3. Enter User Management App as the Application Name and click Create. This creates the application and takes you to the application overview page.
                                                  4. In the Developer Portal left navigation menu, click Production under Credentials.
                                                  5. Click to expand Advanced Configurations and follow these steps to generate credentials for the application:
                                                    1. Select Code as the grant type.
                                                    2. Enter the hosted URL of the application as the Callback URL.
                                                    3. Click Generate Credentials.
                                                  6. To subscribe to the API follow these steps:
                                                    1. In the Developer Portal left navigation menu, click Subscriptions.
                                                    2. In the Subscription Management pane, click Add APIs.
                                                    3. In the Add APIs list, go to the API you created, and click Add.
                                                  "},{"location":"tutorials/secure-an-api-with-role-based-access-control/#step-4-define-roles-and-assign-them-to-groups","title":"Step 4: Define roles and assign them to groups","text":"

                                                  In this step, you define roles, create necessary groups and assign appropriate roles to groups so that you can easily manage user permission.

                                                  Follow these steps:

                                                  1. In the Developer Portal left navigation menu, click Production under Credentials.

                                                  2. In the Permissions section, click Manage Permissions. This takes you to the Roles tab of the User Management App application in Asgardeo, where you can add applicable roles.

                                                  3. Follow these steps to add roles:

                                                    1. Click + New Role, enter admin as the Role Name, and click Next.
                                                    2. Select get_user_list, get_user, create_user, and delete_useras Role Permissions.
                                                    3. Click Finish.
                                                    4. Similarly, add another role with user as the Role Name and get_user_list, and get_user as Role Permissions.

                                                    Now you can proceed to create groups and assign applicable roles to the groups.

                                                  4. In the Asgardeo Console left navigation menu, click User Management and then click Groups.

                                                  5. In the Groups pane, follow these steps to add groups and assign roles:
                                                    1. Click + New Group, enter HR-Manager as the Group Name, and click Finish.
                                                    2. Click the Roles tab in the HR-Manager group you created and then click + Assign Roles.
                                                    3. Click the arrow corresponding to the User Management App to view applicable roles and select admin.
                                                    4. Click Save.
                                                    5. Similarly, add another group with HR-Officer as the Group Name and assign the user role to it.
                                                  "},{"location":"tutorials/secure-an-api-with-role-based-access-control/#step-5-define-users-and-assign-them-to-groups","title":"Step 5: Define users and assign them to groups","text":"

                                                  In this step, you define users and assign them to groups depending on the job function of the user. This allows you to manage permission at the group level instead of for individual users.

                                                  Follow these steps:

                                                  1. Define two users named Cameron and Alex. For step-by-step instructions on adding a user, see Manage users in the Asgardeo documentation.
                                                  2. Assign Cameron to the HR-Manager group and assign Alex to the HR-Officer group. For step-by-step instructions on assigning a user to a group, see Assign groups in the Asgardeo documentation.
                                                  "},{"location":"tutorials/secure-an-api-with-role-based-access-control/#step-6-obtain-an-access-token-and-try-out-the-api","title":"Step 6: Obtain an access token and try out the API","text":"

                                                  Follow these steps:

                                                  1. Construct the authorization URL as follows by replacing the placeholders with appropriate values:

                                                    <authorize_URL>?response_type=code&client_id=<clientID>&redirect_uri=<redirect_URL>&scope=<scopes>\n

                                                    • Replace <authorize URL> with the URL populated as the Authorize Endpoint in the Application Keys pane.

                                                    • Replace <redirect_URL> with the value specified as the Callback URL under Advanced Configurations in the Application Keys pane.

                                                    • Replace <scopes> with the permission(scopes) applicable to the user. You can copy the applicable permission(scopes) from the API Overview page. Here let\u2019s copy the permission(scopes) applicable to the user Alex.

                                                    • Replace <clientID> with the value populated as Consumer Key in the Application Keys pane.

                                                  2. Open the constructed URL via a web browser. This will take you to a sign-in page provided by Asgardeo.

                                                  3. Sign in with credentials of Alex and click Allow to approve the consent.

                                                    This redirects you to the callback URL of the application. The URL includes a code as a query parameter.

                                                  4. Copy the code and use it to replace <code> in the following cURL command to invoke the authorization code grant token request:

                                                    curl <token_url> -d \"grant_type=authorization_code&code=<code>&redirect_uri=<redirect_uri>\" -H \"Authorization: Basic <base64(clientId:clientSecret)>\"\n

                                                    • Replace <token_url> with the URL populated as the Token Endpoint in the Application Keys pane.

                                                    • Replace <redirect_uri> with the value specified as the Callback URL under Advanced Configurations in the Application Keys pane.

                                                    • Use a Base64 encoder to encode your client ID and client secret in the following format and replace <base64(clientId:clientSecret)> with the encoded value:

                                                      <clientId>:<clientSecret>

                                                      Note

                                                      WSO2 does not recommend the use of online Base64 encoders for this purpose.

                                                  5. Extract the access token from the response that you get.

                                                  6. Go to the API Developer Portal, try out the HR API using the access token you extracted, and observe the responses.

                                                    You\u2019ll observe that it is only possible to access the following resources because the access token only contains the permission(scopes) to invoke those resources:

                                                    • GET /users
                                                    • GET /users/{userID}

                                                    Invoking any other resource gives you a scope validation failed response because the token doesn't include the required scopes to invoke them.

                                                  Similarly, if you use Cameron\u2019s credentials and sign in to obtain an access token, you'll observe that you can invoke all four resources because it would contain all the required permission(scopes).

                                                  Now you have gained hands-on experience in implementing role-based access control with Choreo and Asgardeo.

                                                  "}]} \ No newline at end of file diff --git a/en/site/sitemap.xml b/en/site/sitemap.xml deleted file mode 100644 index bee42de25..000000000 --- a/en/site/sitemap.xml +++ /dev/null @@ -1,598 +0,0 @@ - - - - https://wso2.com/choreo/docs/ - 2024-09-23 - daily - - - https://wso2.com/choreo/docs/page-not-found/ - 2024-09-23 - daily - - - https://wso2.com/choreo/docs/what-is-choreo/ - 2024-09-23 - daily - - - https://wso2.com/choreo/docs/administer/configure-a-custom-domain-for-your-organization/ - 2024-09-23 - daily - - - https://wso2.com/choreo/docs/administer/configure-a-user-store-with-built-in-idp/ - 2024-09-23 - daily - - - https://wso2.com/choreo/docs/administer/configure-enterprise-login/ - 2024-09-23 - daily - - - https://wso2.com/choreo/docs/administer/configure-self-sign-up/ - 2024-09-23 - daily - - - https://wso2.com/choreo/docs/administer/control-access-in-the-choreo-console/ - 2024-09-23 - daily - - - https://wso2.com/choreo/docs/administer/create-api-subscription-plans/ - 2024-09-23 - daily - - - https://wso2.com/choreo/docs/administer/customize-the-developer-portal/ - 2024-09-23 - daily - - - https://wso2.com/choreo/docs/administer/inviting-members/ - 2024-09-23 - daily - - - https://wso2.com/choreo/docs/administer/manage-members-of-an-organization/ - 2024-09-23 - daily - - - https://wso2.com/choreo/docs/administer/configure-an-external-idp/configure-asgardeo-as-an-external-idp/ - 2024-09-23 - daily - - - https://wso2.com/choreo/docs/administer/configure-an-external-idp/configure-azure-ad-as-an-external-idp/ - 2024-09-23 - daily - - - https://wso2.com/choreo/docs/api-management/api-policies/ - 2024-09-23 - daily - - - https://wso2.com/choreo/docs/api-management/api-rate-limiting/ - 2024-09-23 - daily - - - https://wso2.com/choreo/docs/api-management/control-api-visibility/ - 2024-09-23 - daily - - - https://wso2.com/choreo/docs/api-management/documents/ - 2024-09-23 - daily - - - https://wso2.com/choreo/docs/api-management/lifecycle-management/ - 2024-09-23 - daily - - - https://wso2.com/choreo/docs/api-management/rename-api-display-name/ - 2024-09-23 - daily - - - https://wso2.com/choreo/docs/api-management/manage-api-traffic/assign-subscription-plans-to-apis/ - 2024-09-23 - daily - - - https://wso2.com/choreo/docs/api-management/manage-api-traffic/subscribe-to-an-api-with-a-subscription-plan/ - 2024-09-23 - daily - - - https://wso2.com/choreo/docs/authentication-and-authorization/configure-mutual-tls-between-components/ - 2024-09-23 - daily - - - https://wso2.com/choreo/docs/authentication-and-authorization/pass-end-user-attributes-to-upstream-services/ - 2024-09-23 - daily - - - https://wso2.com/choreo/docs/authentication-and-authorization/secure-api-access-with-asgardeo/ - 2024-09-23 - daily - - - https://wso2.com/choreo/docs/authentication-and-authorization/secure-api-access-with-azure-ad/ - 2024-09-23 - daily - - - https://wso2.com/choreo/docs/authentication-and-authorization/secure-communication-between-the-choreo-gateway-and-your-backend-with-mutual-tls/ - 2024-09-23 - daily - - - https://wso2.com/choreo/docs/authentication-and-authorization/secure-web-applications-with-managed-authentication/ - 2024-09-23 - daily - - - https://wso2.com/choreo/docs/authentication-and-authorization/test-secure-api-access-with-choreo-built-in-security-token-service/ - 2024-09-23 - daily - - - https://wso2.com/choreo/docs/choreo-cli/choreo-cli-overview/ - 2024-09-23 - daily - - - https://wso2.com/choreo/docs/choreo-cli/get-started-with-the-choreo-cli/ - 2024-09-23 - daily - - - https://wso2.com/choreo/docs/choreo-concepts/choreo-marketplace/ - 2024-09-23 - daily - - - https://wso2.com/choreo/docs/choreo-concepts/ci-cd/ - 2024-09-23 - daily - - - https://wso2.com/choreo/docs/choreo-concepts/component/ - 2024-09-23 - daily - - - https://wso2.com/choreo/docs/choreo-concepts/connections/ - 2024-09-23 - daily - - - https://wso2.com/choreo/docs/choreo-concepts/data-planes/ - 2024-09-23 - daily - - - https://wso2.com/choreo/docs/choreo-concepts/deployment-tracks/ - 2024-09-23 - daily - - - https://wso2.com/choreo/docs/choreo-concepts/endpoint/ - 2024-09-23 - daily - - - https://wso2.com/choreo/docs/choreo-concepts/environments/ - 2024-09-23 - daily - - - https://wso2.com/choreo/docs/choreo-concepts/organization/ - 2024-09-23 - daily - - - https://wso2.com/choreo/docs/choreo-concepts/project/ - 2024-09-23 - daily - - - https://wso2.com/choreo/docs/choreo-concepts/resource-hierarchy/ - 2024-09-23 - daily - - - https://wso2.com/choreo/docs/consuming-services/consuming-a-sevice/ - 2024-09-23 - daily - - - https://wso2.com/choreo/docs/consuming-services/create-a-subscription/ - 2024-09-23 - daily - - - https://wso2.com/choreo/docs/consuming-services/create-an-application/ - 2024-09-23 - daily - - - https://wso2.com/choreo/docs/consuming-services/generate-an-access-token/ - 2024-09-23 - daily - - - https://wso2.com/choreo/docs/consuming-services/manage-application/ - 2024-09-23 - daily - - - https://wso2.com/choreo/docs/consuming-services/manage-subscription/ - 2024-09-23 - daily - - - https://wso2.com/choreo/docs/consuming-services/share-applications/ - 2024-09-23 - daily - - - https://wso2.com/choreo/docs/develop-components/bring-your-own-image/ - 2024-09-23 - daily - - - https://wso2.com/choreo/docs/develop-components/configure-endpoints-body/ - 2024-09-23 - daily - - - https://wso2.com/choreo/docs/develop-components/configure-endpoints/ - 2024-09-23 - daily - - - https://wso2.com/choreo/docs/develop-components/deploy-a-containerized-application/ - 2024-09-23 - daily - - - https://wso2.com/choreo/docs/develop-components/deploy-an-application-with-buildpacks/ - 2024-09-23 - daily - - - https://wso2.com/choreo/docs/develop-components/develop-a-webhook/ - 2024-09-23 - daily - - - https://wso2.com/choreo/docs/develop-components/develop-an-api-proxy/ - 2024-09-23 - daily - - - https://wso2.com/choreo/docs/develop-components/develop-components-using-vs-code/ - 2024-09-23 - daily - - - https://wso2.com/choreo/docs/develop-components/develop-components-with-git/ - 2024-09-23 - daily - - - https://wso2.com/choreo/docs/develop-components/manage-deployment-tracks-for-choreo-components/ - 2024-09-23 - daily - - - https://wso2.com/choreo/docs/develop-components/manage-the-micro-integrator-runtime-version-in-your-integration-project/ - 2024-09-23 - daily - - - https://wso2.com/choreo/docs/develop-components/work-with-the-micro-integrator-runtime-in-choreo/ - 2024-09-23 - daily - - - https://wso2.com/choreo/docs/develop-components/develop-integrations/develop-a-manual-task/ - 2024-09-23 - daily - - - https://wso2.com/choreo/docs/develop-components/develop-integrations/develop-a-scheduled-task/ - 2024-09-23 - daily - - - https://wso2.com/choreo/docs/develop-components/develop-integrations/develop-an-event-handler/ - 2024-09-23 - daily - - - https://wso2.com/choreo/docs/develop-components/develop-integrations/develop-an-integration-with-integration-studio/ - 2024-09-23 - daily - - - https://wso2.com/choreo/docs/develop-components/develop-services/develop-a-ballerina-service/ - 2024-09-23 - daily - - - https://wso2.com/choreo/docs/develop-components/develop-services/develop-a-service-with-docker/ - 2024-09-23 - daily - - - https://wso2.com/choreo/docs/develop-components/develop-services/develop-a-service/ - 2024-09-23 - daily - - - https://wso2.com/choreo/docs/develop-components/develop-services/expose-a-ballerina-graphql-endpoint-via-a-service/ - 2024-09-23 - daily - - - https://wso2.com/choreo/docs/develop-components/develop-services/expose-a-grpc-endpoint-via-a-service/ - 2024-09-23 - daily - - - https://wso2.com/choreo/docs/develop-components/develop-services/expose-a-tcp-server-via-a-service/ - 2024-09-23 - daily - - - https://wso2.com/choreo/docs/develop-components/develop-services/expose-a-udp-server-via-a-service/ - 2024-09-23 - daily - - - https://wso2.com/choreo/docs/develop-components/develop-services/service-component-overview/ - 2024-09-23 - daily - - - https://wso2.com/choreo/docs/develop-components/develop-web-applications/build-and-deploy-a-single-page-web-application/ - 2024-09-23 - daily - - - https://wso2.com/choreo/docs/develop-components/develop-web-applications/develop-web-applications-locally-with-managed-authentication/ - 2024-09-23 - daily - - - https://wso2.com/choreo/docs/develop-components/sharing-and-reusing/create-a-connection/ - 2024-09-23 - daily - - - https://wso2.com/choreo/docs/develop-components/sharing-and-reusing/use-a-connection-in-your-service/ - 2024-09-23 - daily - - - https://wso2.com/choreo/docs/develop-components/sharing-and-reusing/use-a-connection-in-your-web-application/ - 2024-09-23 - daily - - - https://wso2.com/choreo/docs/devops-and-ci-cd/autoscale-component-replicas/ - 2024-09-23 - daily - - - https://wso2.com/choreo/docs/devops-and-ci-cd/configure-container-resources-commands-and-arguments/ - 2024-09-23 - daily - - - https://wso2.com/choreo/docs/devops-and-ci-cd/configure-storage/ - 2024-09-23 - daily - - - https://wso2.com/choreo/docs/devops-and-ci-cd/configure-vpns-on-the-choreo-cloud-data-plane/ - 2024-09-23 - daily - - - https://wso2.com/choreo/docs/devops-and-ci-cd/manage-configurations-and-secrets/ - 2024-09-23 - daily - - - https://wso2.com/choreo/docs/devops-and-ci-cd/manage-environments/ - 2024-09-23 - daily - - - https://wso2.com/choreo/docs/devops-and-ci-cd/set-up-health-checks/ - 2024-09-23 - daily - - - https://wso2.com/choreo/docs/devops-and-ci-cd/view-runtime-details/ - 2024-09-23 - daily - - - https://wso2.com/choreo/docs/devops-and-ci-cd/autoscale/autoscale-component-replicas/ - 2024-09-23 - daily - - - https://wso2.com/choreo/docs/devops-and-ci-cd/autoscale/autoscale-components-with-scale-to-zero/ - 2024-09-23 - daily - - - https://wso2.com/choreo/docs/manage-databases-and-caches/billing-for-platform-services/ - 2024-09-23 - daily - - - https://wso2.com/choreo/docs/manage-databases-and-caches/choreo-managed-caches/ - 2024-09-23 - daily - - - https://wso2.com/choreo/docs/manage-databases-and-caches/choreo-managed-databases-and-caches/ - 2024-09-23 - daily - - - https://wso2.com/choreo/docs/manage-databases-and-caches/choreo-managed-mysql-databases/ - 2024-09-23 - daily - - - https://wso2.com/choreo/docs/manage-databases-and-caches/choreo-managed-postgresql-databases/ - 2024-09-23 - daily - - - https://wso2.com/choreo/docs/monitoring-and-insights/generate-custom-reports/ - 2024-09-23 - daily - - - https://wso2.com/choreo/docs/monitoring-and-insights/insights-overview/ - 2024-09-23 - daily - - - https://wso2.com/choreo/docs/monitoring-and-insights/integrate-choreo-with-moesif/ - 2024-09-23 - daily - - - https://wso2.com/choreo/docs/monitoring-and-insights/observability-overview/ - 2024-09-23 - daily - - - https://wso2.com/choreo/docs/monitoring-and-insights/view-logs/ - 2024-09-23 - daily - - - https://wso2.com/choreo/docs/monitoring-and-insights/alerts/configure-alerts/ - 2024-09-23 - daily - - - https://wso2.com/choreo/docs/monitoring-and-insights/delivery-insights/configure-dora-metrics/ - 2024-09-23 - daily - - - https://wso2.com/choreo/docs/monitoring-and-insights/delivery-insights/view-dora-metrics/ - 2024-09-23 - daily - - - https://wso2.com/choreo/docs/monitoring-and-insights/logs/view-pdp-logs/ - 2024-09-23 - daily - - - https://wso2.com/choreo/docs/monitoring-and-insights/work-with-choreo-insights-api/access-the-choreo-insights-api/ - 2024-09-23 - daily - - - https://wso2.com/choreo/docs/monitoring-and-insights/work-with-choreo-insights-api/choreo-insights-api/ - 2024-09-23 - daily - - - https://wso2.com/choreo/docs/quick-start-guides/deploy-a-web-application-that-consumes-a-backend-service/ - 2024-09-23 - daily - - - https://wso2.com/choreo/docs/quick-start-guides/deploy-your-first-service/ - 2024-09-23 - daily - - - https://wso2.com/choreo/docs/quick-start-guides/deploy-your-first-static-web-application/ - 2024-09-23 - daily - - - https://wso2.com/choreo/docs/references/choreo-limitations/ - 2024-09-23 - daily - - - https://wso2.com/choreo/docs/references/faq/ - 2024-09-23 - daily - - - https://wso2.com/choreo/docs/references/private-data-plane-management-models/ - 2024-09-23 - daily - - - https://wso2.com/choreo/docs/references/private-data-plane-security-levels/ - 2024-09-23 - daily - - - https://wso2.com/choreo/docs/references/troubleshoot-choreo/ - 2024-09-23 - daily - - - https://wso2.com/choreo/docs/testing/test-apis-with-choreo-apichat/ - 2024-09-23 - daily - - - https://wso2.com/choreo/docs/testing/test-apis-with-curl/ - 2024-09-23 - daily - - - https://wso2.com/choreo/docs/testing/test-components-with-test-runner/ - 2024-09-23 - daily - - - https://wso2.com/choreo/docs/testing/test-graphql-endpoints-via-the-graphql-console/ - 2024-09-23 - daily - - - https://wso2.com/choreo/docs/testing/test-rest-endpoints-via-the-openapi-console/ - 2024-09-23 - daily - - - https://wso2.com/choreo/docs/tutorials/expose-a-service-as-a-managed-api/ - 2024-09-23 - daily - - - https://wso2.com/choreo/docs/tutorials/secure-an-api-with-role-based-access-control/ - 2024-09-23 - daily - - \ No newline at end of file diff --git a/en/site/sitemap.xml.gz b/en/site/sitemap.xml.gz deleted file mode 100644 index 46fbc060f..000000000 Binary files a/en/site/sitemap.xml.gz and /dev/null differ diff --git a/en/site/test/curl/index.html b/en/site/test/curl/index.html deleted file mode 100644 index abb2b9867..000000000 --- a/en/site/test/curl/index.html +++ /dev/null @@ -1,15 +0,0 @@ - - - - - - Redirecting... - - - - - - -Redirecting... - - diff --git a/en/site/test/graphql-console/index.html b/en/site/test/graphql-console/index.html deleted file mode 100644 index 8a527d7c7..000000000 --- a/en/site/test/graphql-console/index.html +++ /dev/null @@ -1,15 +0,0 @@ - - - - - - Redirecting... - - - - - - -Redirecting... - - diff --git a/en/site/test/invoke-apis-via-console/index.html b/en/site/test/invoke-apis-via-console/index.html deleted file mode 100644 index 5c4fb5a46..000000000 --- a/en/site/test/invoke-apis-via-console/index.html +++ /dev/null @@ -1,15 +0,0 @@ - - - - - - Redirecting... - - - - - - -Redirecting... - - diff --git a/en/site/test/open-api-console/index.html b/en/site/test/open-api-console/index.html deleted file mode 100644 index 5c4fb5a46..000000000 --- a/en/site/test/open-api-console/index.html +++ /dev/null @@ -1,15 +0,0 @@ - - - - - - Redirecting... - - - - - - -Redirecting... - - diff --git a/en/site/testing/test-apis-with-choreo-apichat/index.html b/en/site/testing/test-apis-with-choreo-apichat/index.html deleted file mode 100644 index 14510f927..000000000 --- a/en/site/testing/test-apis-with-choreo-apichat/index.html +++ /dev/null @@ -1,3201 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - Test APIs with Choreo API Chat - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
                                                  - - - -
                                                  - - - - - - -
                                                  - - -
                                                  - -
                                                  - - - - - - - -
                                                  -
                                                  - - - -
                                                  -
                                                  -
                                                  - - - - -
                                                  -
                                                  -
                                                  - - - -
                                                  -
                                                  -
                                                  - - - -
                                                  -
                                                  -
                                                  - - - -
                                                  -
                                                  - - - - - - - - - - - - - - - - - - - - -

                                                  Test APIs with Choreo API Chat

                                                  -

                                                  Testing APIs is an essential step in the API development process. Choreo simplifies the testing task by allowing you to engage with your APIs using natural language through Choreo API Chat. It eliminates manual test scenario creation and JSON payload accuracy concerns. It enables easy API communication using human language and requires no coding for handling sequences with multiple resource calls. This makes your API testing efficient and user-friendly.

                                                  -
                                                  -

                                                  Info

                                                  -

                                                  This feature is available for REST API Proxy components and Service components with REST endpoints.

                                                  -
                                                  -

                                                  Prerequisites

                                                  -

                                                  Before you try out this guide, be sure that you have the following:

                                                  - -

                                                  Test your APIs

                                                  -

                                                  Follow the steps below to test an API with API Chat:

                                                  -
                                                    -
                                                  1. Sign in to the Choreo Console.
                                                    2. -
                                                  2. In the Component Listing pane, click on the component you want to test.
                                                    3. -
                                                  3. On the left navigation, click Test and then click API Chat. This opens the API Chat pane.
                                                    4. -
                                                  4. You can enter your query in natural language and execute it. For example, if you have a resource like "/pet/findByStatus," you can input the query, such as "Get the pets that are available," and execute it to obtain results. The resources are executed sequentially based on your query. Alternatively, you can use the sample queries available to try out API Chat.
                                                    5. -
                                                  - - - - - - -
                                                  -
                                                  - - -
                                                  - - - -
                                                  - - -
                                                  - - - -
                                                  -
                                                  -
                                                  - - - - - - - - - - - - - - - - - \ No newline at end of file diff --git a/en/site/testing/test-apis-with-choreo-testgpt/index.html b/en/site/testing/test-apis-with-choreo-testgpt/index.html deleted file mode 100644 index d63c3fb45..000000000 --- a/en/site/testing/test-apis-with-choreo-testgpt/index.html +++ /dev/null @@ -1,15 +0,0 @@ - - - - - - Redirecting... - - - - - - -Redirecting... - - diff --git a/en/site/testing/test-apis-with-curl/index.html b/en/site/testing/test-apis-with-curl/index.html deleted file mode 100644 index e3e683cc9..000000000 --- a/en/site/testing/test-apis-with-curl/index.html +++ /dev/null @@ -1,3124 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - Test APIs with cURL - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
                                                  - - - -
                                                  - - - - - - -
                                                  - - -
                                                  - -
                                                  - - - - - - - -
                                                  -
                                                  - - - -
                                                  -
                                                  -
                                                  - - - - -
                                                  -
                                                  -
                                                  - - - -
                                                  -
                                                  -
                                                  - - - -
                                                  -
                                                  -
                                                  - - - -
                                                  -
                                                  - - - - - - - - - - - - - - - - - - - - -

                                                  Test APIs with cURL

                                                  -

                                                  Testing APIs is an essential step in the API development process. Choreo simplifies the testing task by allowing you to use cURL commands generated by Choreo.

                                                  -

                                                  You can follow the steps below to generate a cURL command and test your API method:

                                                  -
                                                    -
                                                  1. -

                                                    Sign in to the Choreo Console.

                                                    -
                                                    2. -
                                                  2. -

                                                    In the Component Listing pane, click on the component you want to test.

                                                    -
                                                    3. -
                                                  3. -

                                                    Click Test in the left navigation menu and then click cURL. This opens the cURL pane.

                                                    -
                                                    4. -
                                                  4. -

                                                    In the cURL pane, select the environment from the drop-down list.

                                                    -
                                                    5. -
                                                  5. -

                                                    Select an appropriate HTTP method from the Method list.

                                                    -
                                                    6. -
                                                  6. -

                                                    Click the Parameters tab and add the necessary parameters for the API method.

                                                    -
                                                    7. -
                                                  7. -

                                                    Click the Headers tab and add the required header values.

                                                    -
                                                    8. -
                                                  8. -

                                                    Click the Body tab and select the message body type to invoke the API method.

                                                    -
                                                    9. -
                                                  9. -

                                                    Copy the generated cURL command.

                                                    -
                                                    10. -
                                                  10. -

                                                    Use the copied cURL command via a cURL client to test your API method.

                                                    -
                                                    11. -
                                                  - - - - - - -
                                                  -
                                                  - - -
                                                  - - - -
                                                  - - -
                                                  - - - -
                                                  -
                                                  -
                                                  - - - - - - - - - - - - - - - - - \ No newline at end of file diff --git a/en/site/testing/test-components-with-test-runner/index.html b/en/site/testing/test-components-with-test-runner/index.html deleted file mode 100644 index d3efd3378..000000000 --- a/en/site/testing/test-components-with-test-runner/index.html +++ /dev/null @@ -1,3399 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - Test Components with Test Runner - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
                                                  - - - -
                                                  - - - - - - -
                                                  - - -
                                                  - -
                                                  - - - - - - - -
                                                  -
                                                  - - - -
                                                  -
                                                  -
                                                  - - - - -
                                                  -
                                                  -
                                                  - - - -
                                                  -
                                                  -
                                                  - - - -
                                                  -
                                                  -
                                                  - - - -
                                                  -
                                                  - - - - - - - - - - - - - - - - - - - - -

                                                  Test Components with Test Runner

                                                  -

                                                  Test Runner is a component type in Choreo that simplifies the process of running automated tests against your components deployed in Choreo. This capability helps developers evaluate applications in different setups and environments, leading to more confidence and improved visibility into the application's status.

                                                  -

                                                  You can create tests using popular programming languages like Go, Java, JavaScript, Python, and more. Additionally, you have the option to build a test runner component by supplying a Dockerfile containing a series of test scripts or by offering a set of Postman Collections.

                                                  -

                                                  Prerequisites

                                                  -

                                                  Before you try out the steps in this guide, complete the following:

                                                  -
                                                    -
                                                  • If you are signing in to the Choreo Console for the first time, create an organization as follows:
                                                      -
                                                    1. Go to https://console.choreo.dev/, and sign in using your preferred method.
                                                      2. -
                                                    2. Enter a unique organization name. For example, Stark Industries.
                                                      3. -
                                                    3. Read and accept the privacy policy and terms of use.
                                                      4. -
                                                    4. Click Create. - This creates the organization and opens the Project Home page of the default project created for you.
                                                      5. -
                                                    -
                                                    • -
                                                  • Fork the Choreo examples repository, which contains the test runner sample for this guide.
                                                    • -
                                                  -

                                                  You can develop tests in a language of your choice and execute them within the Choreo platform.

                                                  -

                                                  Create a test runner component using a buildpack

                                                  -
                                                    -
                                                  1. Go to https://console.choreo.dev/ and sign in. This opens the project home page.
                                                    2. -
                                                  2. Click +Create in the Component Listing section.
                                                    3. -
                                                  3. Click the Test Runner card.
                                                    4. -
                                                  4. -

                                                    Enter a display name, unique name, and description for the test runner component. For this guide, enter the following values:

                                                    -
                                                    -

                                                    Info

                                                    -

                                                    In the Component Name field, you must specify a name to uniquely identify the component in various contexts. The value is editable only at the time you create the component. You cannot change the name after you create the component.

                                                    -
                                                    - - - - - - - - - - - - - - - - - - - - - -
                                                    FieldValue
                                                    Component Display NameGo Test Runner
                                                    Component Namego-test-runner
                                                    DescriptionTest Runner implemented in Go
                                                    -
                                                    5. -
                                                  5. -

                                                    Go to the GitHub tab.

                                                    -
                                                    6. -
                                                  6. -

                                                    To allow Choreo to connect to your GitHub account, click Authorize with GitHub. If you have not already connected your GitHub repository to Choreo, enter your GitHub credentials and select the repository you created in the prerequisites section to install the Choreo GitHub App.

                                                    -

                                                    Alternatively, you can paste the Choreo samples repository URL in the Provide Repository URL field to connect to it without requiring authorization from the Choreo Apps GitHub application. However, authorizing the repository with the Choreo GitHub App is necessary if you want to enable Auto Deploy for the component.

                                                    -
                                                    -

                                                    Note

                                                    -

                                                    The Choreo GitHub App requires the following permissions:

                                                    -
                                                      -
                                                    • Read and write access to code and pull requests.
                                                      • -
                                                    • Read access to issues and metadata.
                                                      • -
                                                    -

                                                    You can revoke access if you do not want Choreo to have access to your GitHub account. However, write access is exclusively utilized for sending pull requests to a user repository. Choreo will not directly push any changes to a repository.

                                                    -
                                                    -
                                                    7. -
                                                  7. -

                                                    Under Connect Your Repository, enter the following information:

                                                    - - - - - - - - - - - - - - - - - - - - - -
                                                    FieldValue
                                                    OrganizationYour GitHub account
                                                    GitHub Repositorychoreo-samples
                                                    Branchmain
                                                    -
                                                    8. -
                                                  8. -

                                                    Under Buildpack, select a buildpack based on the language of your choice.

                                                    -
                                                    9. -
                                                  9. -

                                                    Based on the buildpack you chose, go to the relevant tab below and enter the respective values for the Project directory and Language version fields:

                                                    -
                                                    -
                                                    -
                                                    - - - - - - - - - - - - - - - - - -
                                                    FieldValue
                                                    Go Project Directory/test-runner-go
                                                    Language Version1.x
                                                    -
                                                    -
                                                    - - - - - - - - - - - - - - - - - -
                                                    FieldValue
                                                    Project Directory/test-runner-javascript
                                                    Language Version18.x.x
                                                    -
                                                    -
                                                    - - - - - - - - - - - - - - - - - -
                                                    FieldValue
                                                    Project Directory/test-runner-python
                                                    Language Version3.10.x
                                                    -
                                                    -
                                                    - - - - - - - - - - - - - - - - - -
                                                    FieldValue
                                                    Project Directory/test-runner-java
                                                    Language Version17
                                                    -
                                                    -
                                                    -

                                                    For programming languages that doesn't support buildpacks or for advanced use cases, you can define your own Dockerfile and run test workloads. Refer to for more information.

                                                    -
                                                    -
                                                    - - - - - - - - - - - - - -
                                                    FieldValue
                                                    Postman Directory/postman-collection-dir
                                                    -
                                                    -
                                                    -
                                                    -
                                                    10. -
                                                  10. -

                                                    Click Create.

                                                    -
                                                    11. -
                                                  -

                                                  You have successfully created a Test Runner component using a buildpack of your choice. Now let's build and run the tests.

                                                  -

                                                  Build and deploy the test runner component to execute the tests

                                                  -
                                                    -
                                                  1. In the left navigation menu, click Build.
                                                    2. -
                                                  2. In the Builds pane, click Build Latest.
                                                    3. -
                                                  3. On the left navigation, click Deploy.
                                                    4. -
                                                  4. In the Set Up card, click Deploy to deploy the test runner component. If you want to provide additional configuration or secrets, use the Configure and Deploy option from the list.
                                                    5. -
                                                  5. Once the deployment is successful, click Execute in the left navigation menu.
                                                    6. -
                                                  6. Select the environment from the environment list and click Run Now to trigger a test execution.
                                                    7. -
                                                  7. -

                                                    Once the execution is completed it is listed on the execution page. This may take some time. Once the execution is listed, you can click on a particular execution to view the test result(s).

                                                    -
                                                    -

                                                    Inject dynamic values into your application as command-line arguments

                                                    -

                                                    If you want to inject dynamic values into your application as command-line arguments when you run a test runner component, follow the steps given below:

                                                    -
                                                      -
                                                    1. Click the drop-down icon next to Run Now and then click Run with Arguments.
                                                      2. -
                                                    2. In the Runtime Arguments pane that opens, enter the arguments you want to pass to your application.
                                                      3. -
                                                    3. Click Execute. This triggers the test runner with the specified arguments.
                                                      4. -
                                                    -
                                                    -

                                                    Tip

                                                    -

                                                    For Postman Collections:

                                                    -
                                                      -
                                                    • The default behavior is to run all the collections in the specified directory.
                                                      • -
                                                    • To run specific collections in the directory, use -f or --files as the first argument, followed by a comma-separated list of collections.
                                                      • -
                                                    • Since Choreo uses Newman internally to run Postman Collections, you can pass any valid Newman arguments.
                                                      • -
                                                    -
                                                    -
                                                    -
                                                    8. -
                                                  - - - - - - -
                                                  -
                                                  - - -
                                                  - - - -
                                                  - - -
                                                  - - - -
                                                  -
                                                  -
                                                  - - - - - - - - - - - - - - - - - \ No newline at end of file diff --git a/en/site/testing/test-graphql-endpoints-via-the-graphql-console/index.html b/en/site/testing/test-graphql-endpoints-via-the-graphql-console/index.html deleted file mode 100644 index a5f5a01fe..000000000 --- a/en/site/testing/test-graphql-endpoints-via-the-graphql-console/index.html +++ /dev/null @@ -1,3140 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - Test GraphQL Endpoints via the GraphQL Console - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
                                                  - - - -
                                                  - - - - - - -
                                                  - - -
                                                  - -
                                                  - - - - - - - -
                                                  -
                                                  - - - -
                                                  -
                                                  -
                                                  - - - - -
                                                  -
                                                  -
                                                  - - - -
                                                  -
                                                  -
                                                  - - - -
                                                  -
                                                  -
                                                  - - - -
                                                  -
                                                  - - - - - - - - - - - - - - - - - - - - -

                                                  Test GraphQL Endpoints via the GraphQL Console

                                                  -

                                                  Choreo provides an integrated GraphQL Console to test publicly exposed GraphQL endpoints of Service components you create and deploy. The GraphQL Console allows you to write queries and mutations interactively. As Choreo uses OAuth2.0 authentication by default to secure GraphQL APIs, the GraphQL Console generates test keys to test APIs.

                                                  -

                                                  Follow the steps below to test a GraphQL endpoint via the GraphQL Console:

                                                  -
                                                    -
                                                  1. -

                                                    Sign in to the Choreo Console.

                                                    -
                                                    2. -
                                                  2. -

                                                    In the Component Listing pane, click on the component you want to test.

                                                    -
                                                    3. -
                                                  3. -

                                                    Click Test in the left navigation menu and then click Console. This opens the GraphQL Console pane.

                                                    -
                                                    4. -
                                                  4. -

                                                    In the GraphQL Console pane, select the environment from the drop-down list.

                                                    -
                                                    5. -
                                                  5. -

                                                    Select the required endpoint from the Endpoint list.

                                                    -
                                                    -

                                                    Note

                                                    -
                                                      -
                                                    • The Network Visibility of an endpoint is set in the endpoints.yaml. You can set it to Public, Organization, or Project.
                                                      • -
                                                    • If you have set the Network Visibility of the endpoint in the endpoints.yaml to Public, continue with step 7.
                                                      • -
                                                    • If you have set the Network Visibility of the endpoint in the endpoints.yaml to Organization, the GraphQL endpoint will not be invokable from outside the organization. In this instance, for testing purposes, Choreo allows you to generate a temporay test URL that will be active for 15 minutes. Execute step 6 to generate the temporary URL.
                                                      • -
                                                    -
                                                    -
                                                    6. -
                                                  6. -

                                                    If the Network Visibility of the endpoint is set to Organization, click on Generate URL to generate a temporary test URL that will be active for 15 minutes. Else, skip this step.

                                                    -
                                                    -

                                                    Note

                                                    -

                                                    The temporay test URL will be available only for 15 minutes and it will get expired after. You can deactivate the test URL by clicking on the Deactivate URL button.

                                                    -
                                                    -

                                                    OpenAPI Console

                                                    -
                                                    7. -
                                                  7. -

                                                    Enter the API path and the query or mutation you want to test.

                                                    -
                                                    8. -
                                                  8. -

                                                    Click the play icon.

                                                    -
                                                    -

                                                    Tip

                                                    -

                                                    If you want to generate a required query or mutation for testing via the GraphQL Explorer, click Explorer to open the GraphQL Explorer.

                                                    -
                                                    -
                                                    -

                                                    Note

                                                    -

                                                    GraphQL Explorer has a known issue causing improper construction of list inputs. To work around this, you must manually update the list input in the generated query before executing it.

                                                    -
                                                    -

                                                    GraphQL Console

                                                    -
                                                    9. -
                                                  - - - - - - -
                                                  -
                                                  - - -
                                                  - - - -
                                                  - - -
                                                  - - - -
                                                  -
                                                  -
                                                  - - - - - - - - - - - - - - - - - \ No newline at end of file diff --git a/en/site/testing/test-rest-endpoints-via-the-openapi-console/index.html b/en/site/testing/test-rest-endpoints-via-the-openapi-console/index.html deleted file mode 100644 index d76260237..000000000 --- a/en/site/testing/test-rest-endpoints-via-the-openapi-console/index.html +++ /dev/null @@ -1,3139 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - Test REST Endpoints via the OpenAPI Console - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
                                                  - - - -
                                                  - - - - - - -
                                                  - - -
                                                  - -
                                                  - - - - - - - -
                                                  -
                                                  - - - -
                                                  -
                                                  -
                                                  - - - - -
                                                  -
                                                  -
                                                  - - - -
                                                  -
                                                  -
                                                  - - - -
                                                  -
                                                  -
                                                  - - - -
                                                  -
                                                  - - - - - - - - - - - - - - - - - - - - -

                                                  Test REST Endpoints via the OpenAPI Console

                                                  -

                                                  Choreo provides an integrated OpenAPI Console to test REST endpoints of Service components that you create and deploy. -As Choreo uses OAuth2.0 authentication to secure REST APIs, the OpenAPI Console generates test keys to test APIs.

                                                  -

                                                  Follow the steps below to test a REST endpoint via the integrated OpenAPI Console:

                                                  -
                                                    -
                                                  1. -

                                                    Sign in to the Choreo Console.

                                                    -
                                                    2. -
                                                  2. -

                                                    In the Component Listing pane, click on the component you want to test.

                                                    -
                                                    3. -
                                                  3. -

                                                    Click Test in the left navigation menu and then click Console. This opens the OpenAPI Console pane.

                                                    -
                                                    4. -
                                                  4. -

                                                    In the OpenAPI Console pane, select the environment from the drop-down list.

                                                    -
                                                    5. -
                                                  5. -

                                                    Select the required endpoint from the Endpoint list.

                                                    -
                                                    -

                                                    Note

                                                    -
                                                      -
                                                    • The Network Visibility of an endpoint is set in the endpoints.yaml. You can set it to Public, Organization, or Project.
                                                      • -
                                                    • If you have set the Network Visibility of the endpoint in the endpoints.yaml to Public, go to step 7.
                                                      • -
                                                    • If you have set the Network Visibility of the endpoint in the endpoints.yaml to Organization, the endpoint will not be publicly accessible. However, for testing purposes, Choreo offers the ability to create a temporary test URL that is publicly accessible (secured with OAuth 2.0) and remains active for 15 minutes. To generate the temporary URL, proceed with step 6.
                                                      • -
                                                    -
                                                    -
                                                    6. -
                                                  6. -

                                                    If the Network Visibility of the endpoint is set to Organization, click on Generate URL to generate a temporary test URL that will be active for 15 minutes. Else, skip this step.

                                                    -
                                                    -

                                                    Note

                                                    -

                                                    The temporary test URL will be available only for 15 minutes and it will get expired after. You can deactivate the test URL by clicking on the Deactivate URL button.

                                                    -
                                                    -

                                                    OpenAPI Console

                                                    -
                                                    7. -
                                                  7. -

                                                    Expand the resource you want to test.

                                                    -
                                                    8. -
                                                  8. -

                                                    Click Try it out.

                                                    -
                                                    9. -
                                                  9. -

                                                    Enter values for parameters if applicable.

                                                    -
                                                    10. -
                                                  10. -

                                                    Click Execute. You can see the response body under Responses.

                                                    -

                                                    OpenAPI Console

                                                    -
                                                    11. -
                                                  - - - - - - -
                                                  -
                                                  - - -
                                                  - - - -
                                                  - - -
                                                  - - - -
                                                  -
                                                  -
                                                  - - - - - - - - - - - - - - - - - \ No newline at end of file diff --git a/en/site/troubleshoot/faq/index.html b/en/site/troubleshoot/faq/index.html deleted file mode 100644 index 426317852..000000000 --- a/en/site/troubleshoot/faq/index.html +++ /dev/null @@ -1,15 +0,0 @@ - - - - - - Redirecting... - - - - - - -Redirecting... - - diff --git a/en/site/tutorials/configure-automatic-deployment/index.html b/en/site/tutorials/configure-automatic-deployment/index.html deleted file mode 100644 index 84ba09b6e..000000000 --- a/en/site/tutorials/configure-automatic-deployment/index.html +++ /dev/null @@ -1,15 +0,0 @@ - - - - - - Redirecting... - - - - - - -Redirecting... - - diff --git a/en/site/tutorials/connect-your-existing-ballerina-project-to-choreo/index.html b/en/site/tutorials/connect-your-existing-ballerina-project-to-choreo/index.html deleted file mode 100644 index 8bb3fe766..000000000 --- a/en/site/tutorials/connect-your-existing-ballerina-project-to-choreo/index.html +++ /dev/null @@ -1,15 +0,0 @@ - - - - - - Redirecting... - - - - - - -Redirecting... - - diff --git a/en/site/tutorials/connect-your-own-github-repository-to-choreo/index.html b/en/site/tutorials/connect-your-own-github-repository-to-choreo/index.html deleted file mode 100644 index 8992d9f11..000000000 --- a/en/site/tutorials/connect-your-own-github-repository-to-choreo/index.html +++ /dev/null @@ -1,15 +0,0 @@ - - - - - - Redirecting... - - - - - - -Redirecting... - - diff --git a/en/site/tutorials/construct-statements/index.html b/en/site/tutorials/construct-statements/index.html deleted file mode 100644 index 7a123ea5d..000000000 --- a/en/site/tutorials/construct-statements/index.html +++ /dev/null @@ -1,15 +0,0 @@ - - - - - - Redirecting... - - - - - - -Redirecting... - - diff --git a/en/site/tutorials/create-your-first-rest-api/index.html b/en/site/tutorials/create-your-first-rest-api/index.html deleted file mode 100644 index 349745712..000000000 --- a/en/site/tutorials/create-your-first-rest-api/index.html +++ /dev/null @@ -1,15 +0,0 @@ - - - - - - Redirecting... - - - - - - -Redirecting... - - diff --git a/en/site/tutorials/expose-a-service-as-a-managed-api/index.html b/en/site/tutorials/expose-a-service-as-a-managed-api/index.html deleted file mode 100644 index 857bd8db2..000000000 --- a/en/site/tutorials/expose-a-service-as-a-managed-api/index.html +++ /dev/null @@ -1,3375 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - Expose a Service as a Managed API - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
                                                  - - - -
                                                  - - - - - - -
                                                  - - -
                                                  - -
                                                  - - - - - - - -
                                                  -
                                                  - - - -
                                                  -
                                                  -
                                                  - - - - -
                                                  -
                                                  -
                                                  - - - -
                                                  -
                                                  -
                                                  - - - -
                                                  -
                                                  -
                                                  - - - -
                                                  -
                                                  - - - - - - - - - - - - - - - - - - - - -

                                                  Expose a Service as a Managed API

                                                  -

                                                  Choreo simplifies securely exposing existing services as managed APIs. It also allows you to effectively manage all aspects of an API's lifecycle, security, throttling, and governance so that you can focus more on service development.

                                                  -

                                                  In this tutorial, you will use Choreo to expose a service as an API proxy and publish it to the Choreo Developer Portal for application developers to consume.

                                                  -

                                                  Prerequisites

                                                  -

                                                  Before you try out this tutorial, complete the following:

                                                  -
                                                    -
                                                  • -

                                                    If you are signing in to the Choreo Console for the first time, create an organization as follows:

                                                    -
                                                      -
                                                    1. Go to https://console.choreo.dev/, and sign in using your preferred method.
                                                      2. -
                                                    2. Enter a unique organization name. For example, Stark Industries.
                                                      3. -
                                                    3. Read and accept the privacy policy and terms of use.
                                                      4. -
                                                    4. Click Create.
                                                      5. -
                                                    -

                                                    This creates the organization and opens the Project Home page of the default project created for you.

                                                    -
                                                    • -
                                                  -

                                                  Step 1: Create an API proxy

                                                  -

                                                  To create an API proxy, you can either upload an OpenAPI specification or provide an OpenAPI specification URL. In this tutorial, you will use a URL of a sample OpenAPI specification.

                                                  -

                                                  Follow the steps given below:

                                                  -
                                                    -
                                                  1. Go to https://console.choreo.dev/ and sign in. This opens the project home page.
                                                    2. -
                                                  2. If you already have one or more components in your project, click + Create under Component Listing. Otherwise, proceed to the next step.
                                                    3. -
                                                  3. Click the API Proxy card.
                                                    4. -
                                                  4. In the Create an API Proxy pane that opens, click Try with sample URL.
                                                    5. -
                                                  5. Click Next.
                                                    6. -
                                                  6. -

                                                    Update the populated API proxy details with the values given in the following table:

                                                    -
                                                    -

                                                    Info

                                                    -

                                                    In the Name field, you must specify a name to uniquely identify the component in various contexts. The value is editable only at the time you create the component. You cannot change the name after you create the component.

                                                    -
                                                    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
                                                    FieldValue
                                                    Display NameSwagger Petstore
                                                    Nameswagger-petstore
                                                    Contextapi/v3
                                                    Version1.0
                                                    Targethttps://petstore3.swagger.io/api/v3
                                                    Access ModeExternal: API is publicly accessible
                                                    -
                                                    7. -
                                                  7. -

                                                    Click Create. This creates the component and takes you to the Overview page of the component.

                                                    -
                                                    8. -
                                                  -

                                                  To see the resources of the API proxy, go to the left navigation menu, click Develop, and then click Resources.

                                                  -

                                                  Step 2: Deploy the API proxy

                                                  -

                                                  To deploy the API proxy to the development environment, follow the steps given below:

                                                  -
                                                    -
                                                  1. In the left navigation menu, click Deploy.
                                                    2. -
                                                  2. -

                                                    In the Build Area card, click Configure & Deploy. This opens the Configure & Deploy pane, where you can select the API access mode depending on how you want the API to be accessible.

                                                    -

                                                    Here, you can select External to make the API publicly accessible, and then click Deploy.

                                                    -

                                                    Once the deployment is complete, the Development card indicates the Deployment Status as Active.

                                                    -
                                                    3. -
                                                  -

                                                  Now you are ready to test the API proxy.

                                                  -

                                                  Step 3: Test the API proxy

                                                  -

                                                  You can test the API proxy in the development environment before promoting it to production. Choreo provides the following options to test your API proxy: -- OpenAPI Console -- cURL

                                                  -

                                                  In this guide, you will use the OpenAPI Console.

                                                  -

                                                  To test the API proxy via the OpenAPI Console, follow the steps given below:

                                                  -
                                                    -
                                                  1. -

                                                    In the left navigation menu, click Test and then click OpenAPI Console.

                                                    -
                                                    -

                                                    Tip

                                                    -

                                                    Since the API proxy is secured when it is deployed, you will need a key to invoke it. Choreo automatically generates a key when you navigate to the OpenAPI Console pane.

                                                    -
                                                    -
                                                    2. -
                                                  2. -

                                                    In the OpenAPI Console pane, select Development from the environment drop-down list.

                                                    -
                                                    3. -
                                                  3. Expand the GET /pet/findByStatus method and click Try it Out to test it.
                                                    4. -
                                                  4. -

                                                    Select available as the status and click Execute. You will see a response similar to the following:

                                                    -

                                                    API proxy response

                                                    -
                                                    5. -
                                                  -

                                                  This indicates that your API proxy is working as expected.

                                                  -

                                                  Step 4: Promote the API proxy to production

                                                  -

                                                  Once you verify that the API proxy is working as expected in the development environment, you can follow the steps given below to promote it to production:

                                                  -
                                                    -
                                                  1. In the left navigation menu, click Deploy.
                                                    2. -
                                                  2. In the Development card, click Promote.
                                                    3. -
                                                  3. -

                                                    In the Configure & Deploy pane that opens, click Next.

                                                    -
                                                    -

                                                    Tip

                                                    -

                                                    If you want to specify a different endpoint for your production environment, you can make the change in the Configure & Deploy pane.

                                                    -
                                                    -
                                                    4. -
                                                  -

                                                  The Production card indicates the Deployment Status as Active when the API proxy is successfully deployed to production.

                                                  -

                                                  If you want to verify that the API proxy is working as expected in production, you can test the API in the production environment.

                                                  -

                                                  Now that your API is deployed in both development and production environments and can be invoked, the next step is to publish it so that consumers can discover and subscribe to it.

                                                  -

                                                  Step 5: Publish the API proxy

                                                  -

                                                  To publish the API to the Choreo Developer Portal, follow the steps given below:

                                                  -
                                                    -
                                                  1. In the left navigation menu, click Manage and then click Lifecycle. This opens the Lifecycle page, where you can see the different lifecycle stages that an API can be in. You can see that the current lifecycle stage is Created.
                                                    2. -
                                                  2. Click Publish.
                                                    3. -
                                                  3. In the Publish API dialog that opens, click Confirm to proceed publishing the API with the specified display name. If you want to change the display name, make the necessary changes and then click Confirm. This changes the API lifecycle state to Published.
                                                    4. -
                                                  -

                                                  You can observe that the API lifecycle stage has changed to Published. Now the API is available for consumption. API consumers can consume the API via the Choreo Developer Portal.

                                                  -

                                                  Step 6: Invoke the API

                                                  -

                                                  To generate credentials for the published API and to invoke it via the Developer Portal, follow the steps below:

                                                  -
                                                    -
                                                  1. -

                                                    In the Lifecycle Management pane, click Go to DevPortal. This takes you to the Petstore API published to the Choreo Developer Portal.

                                                    -
                                                    2. -
                                                  2. -

                                                    To generate credentials for testing the API, follow the steps given below:

                                                    -
                                                      -
                                                    1. In the Developer Portal left navigation menu, click Production under Credentials.
                                                      2. -
                                                    2. Click Generate Credentials. Choreo generates new tokens and populates the Consumer Key and Consumer Secret fields.
                                                      3. -
                                                    -
                                                    3. -
                                                  3. -

                                                    To invoke the API, follow the steps given below:

                                                    -
                                                      -
                                                    1. In the Developer Portal left navigation menu, click Try Out.
                                                      2. -
                                                    2. In the Endpoint list, select Development as the environment to try out the API.
                                                      3. -
                                                    3. Click Get Test Key. This generates an access token.
                                                      4. -
                                                    4. Expand the GET /pet/findByStatus operation and click Try it out.
                                                      5. -
                                                    5. Select available as the status and click Execute.
                                                      6. -
                                                    -
                                                    4. -
                                                  -

                                                  Now you have successfully created, deployed, tested, and published an API proxy using Choreo.

                                                  - - - - - - -
                                                  -
                                                  - - -
                                                  - - - -
                                                  - - -
                                                  - - - -
                                                  -
                                                  -
                                                  - - - - - - - - - - - - - - - - - \ No newline at end of file diff --git a/en/site/tutorials/map-data/index.html b/en/site/tutorials/map-data/index.html deleted file mode 100644 index c58674663..000000000 --- a/en/site/tutorials/map-data/index.html +++ /dev/null @@ -1,15 +0,0 @@ - - - - - - Redirecting... - - - - - - -Redirecting... - - diff --git a/en/site/tutorials/secure-an-api-with-role-based-access-control/index.html b/en/site/tutorials/secure-an-api-with-role-based-access-control/index.html deleted file mode 100644 index f90fb733d..000000000 --- a/en/site/tutorials/secure-an-api-with-role-based-access-control/index.html +++ /dev/null @@ -1,3537 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - Secure an API with Role-Based Access Control - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
                                                  - - - -
                                                  - - - - - - -
                                                  - - -
                                                  - -
                                                  - - - - - - - -
                                                  -
                                                  - - - -
                                                  -
                                                  -
                                                  - - - - -
                                                  -
                                                  -
                                                  - - - -
                                                  -
                                                  -
                                                  - - - -
                                                  -
                                                  -
                                                  - - - -
                                                  -
                                                  - - - - - - - - - - - - - - - - - - - - -

                                                  Secure an API with Role-Based Access Control

                                                  -

                                                  Role-based access control is a flexible and scalable approach to manage access to API resources. In this approach, each user or group is assigned a specific role that determines the permission granted to perform operations on an API resource.

                                                  -

                                                  This tutorial explains how to implement role-based access control using Choreo and Asgardeo. It includes a real-world scenario with instructions to create and publish an API proxy component in Choreo and apply role-based access control.

                                                  -

                                                  Scenario

                                                  -

                                                  An organization needs to implement a user management service to keep track of users. The service needs to perform the following four operations:

                                                  -
                                                    -
                                                  • List existing users
                                                    • -
                                                  • List a user
                                                    • -
                                                  • Create new users
                                                    • -
                                                  • Delete a user
                                                    • -
                                                  -

                                                  There are two types of users in the organization:

                                                  -
                                                    -
                                                  • Human Resource Manager (HR manager)
                                                    • -
                                                  • Human Resource Officer (HR officer)
                                                    • -
                                                  -

                                                  Each user type requires different levels of access to the user management service.

                                                  -
                                                    -
                                                  • The HR manager must have permission to perform the following operations: list existing users, list a user, create new users, and delete a user.
                                                    • -
                                                  • The HR officer must have permission to perform the following operations: list existing users and list a user.
                                                    • -
                                                  -

                                                  Implement role-based access control with Choreo and Asgardeo

                                                  -

                                                  Let’s take a look at the steps to follow to implement the scenario described above using Choreo and Asgardeo.

                                                  -

                                                  Prerequisites

                                                  -

                                                  Before you try out this guide, complete the following:

                                                  -

                                                  If you are signing in to the Choreo Console for the first time, create an organization as follows:

                                                  -
                                                    -
                                                  1. Go to https://console.choreo.dev/, and sign in using your preferred method.
                                                    2. -
                                                  2. Enter a unique organization name. For example, Stark Industries.
                                                    3. -
                                                  3. Read and accept the privacy policy and terms of use.
                                                    4. -
                                                  4. Click Create.
                                                    5. -
                                                  -

                                                  This creates the organization and opens the home page of the default project created for you.

                                                  -
                                                  -

                                                  Enable Asgardeo as the key manager

                                                  -

                                                  If you created your organization in Choreo before the 21st of February 2023, and you have not already enabled Asgardeo as the key manager, follow these steps to enable Asgardeo as the default key manager:

                                                  -
                                                    -
                                                  1. In the Choreo Console, go to the top navigation menu and click Organization. This takes you to the organization's home page.
                                                    2. -
                                                  2. In the left navigation menu, click Settings.
                                                    3. -
                                                  3. In the header, click the Organization list. This will open the organization level settings page.
                                                    4. -
                                                  4. Click the API Management tab and then click Enable Asgardeo Key Manager.
                                                    5. -
                                                  5. -

                                                    In the confirmation dialog that opens, click Yes.

                                                    -
                                                    -

                                                    Tip

                                                    -

                                                    Enabling Asgardeo as the default key manager has the following effects:

                                                    -
                                                      -
                                                    • Once the Asgardeo Key Manager is enabled, it will act as the default key manager. You cannot disable, change, or remove it.
                                                      • -
                                                    • Existing applications created via the Developer Portal in your organization will continue to function as usual. However, any new application you create within the organization will use Asgardeo as the key manager.
                                                      • -
                                                    • New grant types such as Password, Authorization Code, PKCE, and Implicit, which were not available in Choreo will become available.
                                                      • -
                                                    • The capability to add an external IdP will be disabled because Asgardeo does not support token exchange. However, you can use the federation capabilities of Asgardeo to achieve similar functionality.
                                                      • -
                                                    -
                                                    -
                                                    6. -
                                                  -
                                                  -

                                                  Step 1: Create an API proxy component and deploy it

                                                  -

                                                  Follow these steps to create an API proxy component, add resources, and deploy it:

                                                  -
                                                    -
                                                  1. Go to https://console.choreo.dev/ and sign in. This opens the project home page.
                                                    2. -
                                                  2. To create an API proxy component, follow the instructions in Develop an API Proxy: Step 1. This opens the Resources pane, where you can define resources for the API proxy.
                                                    3. -
                                                  3. -

                                                    In the Resources pane, follow the steps given below to add resources:

                                                    -
                                                      -
                                                    • Select GET as the HTTP Verb, enter /users as the URI Pattern, and click + to add the resource.
                                                      • -
                                                    • Select GET as the HTTP Verb, enter /users/{userID} as the URI Pattern, and click + to add the resource.
                                                      • -
                                                    • Select POST as the HTTP Verb, enter /users as the URI Pattern, and click + to add the resource.
                                                      • -
                                                    • Select DELETE as the HTTP Verb, enter /users/{userID} as the URI Pattern, and click + to add the resource.
                                                      • -
                                                    -
                                                    4. -
                                                  4. -

                                                    To remove the five default resources that start with /*, click the delete icon corresponding to each resource. This marks the resources for deletion.

                                                    -
                                                    5. -
                                                  5. -

                                                    Click Save. The API resources will be as follows:

                                                    -

                                                    API resources

                                                    -
                                                    6. -
                                                  6. -

                                                    In the left navigation menu, click Deploy.

                                                    -
                                                    7. -
                                                  7. Go to the Build Area card and click Configure & Deploy.
                                                    8. -
                                                  8. In the Configure API Access Mode pane that opens, select either External or Internal, depending on how you want the API to be accessible. In this tutorial, select External.
                                                    9. -
                                                  9. Click Deploy.
                                                    10. -
                                                  -

                                                  Step 2: Apply permission to resources and publish the API

                                                  -

                                                  Follow these steps:

                                                  -
                                                    -
                                                  1. On the Deploy page, go to the Build Area card and click Security Settings.
                                                    2. -
                                                  2. In the Security Settings pane, go to the Permissions List section and click + Add Permission(Scope).
                                                    3. -
                                                  3. To add necessary permission values to the permission list, follow the steps given below:
                                                      -
                                                    1. In the Permissions List section, enter get_user_list as the permission value and click +Add New.
                                                      2. -
                                                    2. Similarly, add get_user, create_user, and delete_user as permission values.
                                                      3. -
                                                    -
                                                    4. -
                                                  4. -

                                                    In the Permissions section, expand each resource and select the permission values as follows for each:

                                                    - - - - - - - - - - - - - - - - - - - - - - - - - -
                                                    ResourcePermission
                                                    GET/usersget_user_list
                                                    GET/users/{userID}get_user
                                                    POST/userscreate_user
                                                    DELETE/users/{userID}delete_user
                                                    -
                                                    5. -
                                                  5. -

                                                    Click Apply.

                                                    -
                                                    6. -
                                                  6. To apply the latest permissions to the deployed component, you must redeploy it. Follow the steps below to redeploy:
                                                      -
                                                    1. Go to the Build Area card and click Configure & Deploy.
                                                      2. -
                                                    2. In the Configure API Access Mode pane that opens, select either External or Internal, depending on how you want the API to be accessible. In this tutorial, select External.
                                                      3. -
                                                    3. Click Deploy.
                                                      4. -
                                                    -
                                                    7. -
                                                  -

                                                  Now you are ready to promote the API to production.

                                                  -
                                                    -
                                                  1. In the left navigation menu, click Deploy.
                                                    2. -
                                                  2. Go to the Development card and click Promote. The Configure & Deploy pane opens with the Use Development endpoint configuration option selected by default.
                                                    3. -
                                                  3. Click Next to promote the API to production. Now you can publish the API
                                                    4. -
                                                  4. In the left navigation menu, click Manage and then click Lifecycle.
                                                    5. -
                                                  5. In the Lifecycle Management pane, click Publish. This changes the status of the API to Published.
                                                    6. -
                                                  -

                                                  Now, an application developer can discover the API, subscribe to it and then invoke it.

                                                  -

                                                  Step 3: Subscribe to the Published API

                                                  -

                                                  In this step, you take the role of an application developer who consumes the published API. -To consume the API, you must create an application, generate keys, and subscribe to the API.

                                                  -

                                                  Follow these steps:

                                                  -
                                                    -
                                                  1. Go to the API Developer Portal and click Applications on the top menu.
                                                    2. -
                                                  2. Click +Create.
                                                    3. -
                                                  3. Enter User Management App as the Application Name and click Create. This creates the application and takes you to the application overview page.
                                                    4. -
                                                  4. In the Developer Portal left navigation menu, click Production under Credentials.
                                                    5. -
                                                  5. Click to expand Advanced Configurations and follow these steps to generate credentials for the application:
                                                      -
                                                    1. Select Code as the grant type.
                                                      2. -
                                                    2. Enter the hosted URL of the application as the Callback URL.
                                                      3. -
                                                    3. Click Generate Credentials.
                                                      4. -
                                                    -
                                                    6. -
                                                  6. To subscribe to the API follow these steps:
                                                      -
                                                    1. In the Developer Portal left navigation menu, click Subscriptions.
                                                      2. -
                                                    2. In the Subscription Management pane, click Add APIs.
                                                      3. -
                                                    3. In the Add APIs list, go to the API you created, and click Add.
                                                      4. -
                                                    -
                                                    7. -
                                                  -

                                                  Step 4: Define roles and assign them to groups

                                                  -

                                                  In this step, you define roles, create necessary groups and assign appropriate roles to groups so that you can easily manage user permission.

                                                  -

                                                  Follow these steps:

                                                  -
                                                    -
                                                  1. In the Developer Portal left navigation menu, click Production under Credentials.
                                                    2. -
                                                  2. -

                                                    In the Permissions section, click Manage Permissions. This takes you to the Roles tab of the User Management App application in Asgardeo, where you can add applicable roles.

                                                    -

                                                    Manage permissions

                                                    -
                                                    3. -
                                                  3. -

                                                    Follow these steps to add roles:

                                                    -
                                                      -
                                                    1. Click + New Role, enter admin as the Role Name, and click Next.
                                                      2. -
                                                    2. Select get_user_list, get_user, create_user, and delete_useras Role Permissions.
                                                      3. -
                                                    3. Click Finish.
                                                      4. -
                                                    4. Similarly, add another role with user as the Role Name and get_user_list, and get_user as Role Permissions.
                                                      5. -
                                                    -

                                                    Now you can proceed to create groups and assign applicable roles to the groups.

                                                    -
                                                    4. -
                                                  4. -

                                                    In the Asgardeo Console left navigation menu, click User Management and then click Groups.

                                                    -
                                                    5. -
                                                  5. In the Groups pane, follow these steps to add groups and assign roles:
                                                      -
                                                    1. Click + New Group, enter HR-Manager as the Group Name, and click Finish.
                                                      2. -
                                                    2. Click the Roles tab in the HR-Manager group you created and then click + Assign Roles.
                                                      3. -
                                                    3. Click the arrow corresponding to the User Management App to view applicable roles and select admin.
                                                      4. -
                                                    4. Click Save.
                                                      5. -
                                                    5. Similarly, add another group with HR-Officer as the Group Name and assign the user role to it.
                                                      6. -
                                                    -
                                                    6. -
                                                  -

                                                  Step 5: Define users and assign them to groups

                                                  -

                                                  In this step, you define users and assign them to groups depending on the job function of the user. This allows you to manage permission at the group level instead of for individual users.

                                                  -

                                                  Follow these steps:

                                                  -
                                                    -
                                                  1. Define two users named Cameron and Alex. For step-by-step instructions on adding a user, see Manage users in the Asgardeo documentation.
                                                    2. -
                                                  2. Assign Cameron to the HR-Manager group and assign Alex to the HR-Officer group. For step-by-step instructions on assigning a user to a group, see Assign groups in the Asgardeo documentation.
                                                    3. -
                                                  -

                                                  Step 6: Obtain an access token and try out the API

                                                  -

                                                  Follow these steps:

                                                  -
                                                    -
                                                  1. -

                                                    Construct the authorization URL as follows by replacing the placeholders with appropriate values:

                                                    -
                                                    <authorize_URL>?response_type=code&client_id=<clientID>&redirect_uri=<redirect_URL>&scope=<scopes>
-
                                                    - -
                                                      -
                                                    • -

                                                      Replace <authorize URL> with the URL populated as the Authorize Endpoint in the Application Keys pane.

                                                      -

                                                      Authorize endpoint

                                                      -
                                                      • -
                                                    • -

                                                      Replace <redirect_URL> with the value specified as the Callback URL under Advanced Configurations in the Application Keys pane.

                                                      -

                                                      Callback URL

                                                      -
                                                      • -
                                                    • -

                                                      Replace <scopes> with the permission(scopes) applicable to the user. You can copy the applicable permission(scopes) from the API Overview page. Here let’s copy the permission(scopes) applicable to the user Alex.

                                                      -

                                                      Scopes

                                                      -
                                                      • -
                                                    • -

                                                      Replace <clientID> with the value populated as Consumer Key in the Application Keys pane.

                                                      -

                                                      Consumer key

                                                      -
                                                      • -
                                                    -
                                                    2. -
                                                  2. -

                                                    Open the constructed URL via a web browser. This will take you to a sign-in page provided by Asgardeo.

                                                    -
                                                    3. -
                                                  3. -

                                                    Sign in with credentials of Alex and click Allow to approve the consent.

                                                    -

                                                    Approve consent

                                                    -

                                                    This redirects you to the callback URL of the application. The URL includes a code as a query parameter.

                                                    -

                                                    Code

                                                    -
                                                    4. -
                                                  4. -

                                                    Copy the code and use it to replace <code> in the following cURL command to invoke the authorization code grant token request:

                                                    -
                                                    curl <token_url> -d "grant_type=authorization_code&code=<code>&redirect_uri=<redirect_uri>" -H "Authorization: Basic <base64(clientId:clientSecret)>"
-
                                                    - -
                                                      -
                                                    • -

                                                      Replace <token_url> with the URL populated as the Token Endpoint in the Application Keys pane.

                                                      -

                                                      Token endpoint

                                                      -
                                                      • -
                                                    • -

                                                      Replace <redirect_uri> with the value specified as the Callback URL under Advanced Configurations in the Application Keys pane.

                                                      -
                                                      • -
                                                    • -

                                                      Use a Base64 encoder to encode your client ID and client secret in the following format and replace <base64(clientId:clientSecret)> with the encoded value:

                                                      -

                                                      <clientId>:<clientSecret>

                                                      -
                                                      -

                                                      Note

                                                      WSO2 does not recommend the use of online Base64 encoders for this purpose.

                                                      -

                                                      -
                                                      -
                                                      • -
                                                    -
                                                    5. -
                                                  5. -

                                                    Extract the access token from the response that you get.

                                                    -

                                                    Access token

                                                    -
                                                    6. -
                                                  6. -

                                                    Go to the API Developer Portal, try out the HR API using the access token you extracted, and observe the responses.

                                                    -

                                                    You’ll observe that it is only possible to access the following resources because the access token only contains the permission(scopes) to invoke those resources:

                                                    -
                                                      -
                                                    • GET /users
                                                      • -
                                                    • GET /users/{userID}
                                                      • -
                                                    -

                                                    Invoking any other resource gives you a scope validation failed response because the token doesn't include the required scopes to invoke them. - Scope validation failed

                                                    -
                                                    7. -
                                                  -

                                                  Similarly, if you use Cameron’s credentials and sign in to obtain an access token, you'll observe that you can invoke all four resources because it would contain all the required permission(scopes).

                                                  -

                                                  Now you have gained hands-on experience in implementing role-based access control with Choreo and Asgardeo.

                                                  - - - - - - -
                                                  -
                                                  - - -
                                                  - - - -
                                                  - - -
                                                  - - - -
                                                  -
                                                  -
                                                  - - - - - - - - - - - - - - - - - \ No newline at end of file diff --git a/en/site/webhook/index.html b/en/site/webhook/index.html deleted file mode 100644 index 7b4b54dd2..000000000 --- a/en/site/webhook/index.html +++ /dev/null @@ -1,15 +0,0 @@ - - - - - - Redirecting... - - - - - - -Redirecting... - - diff --git a/en/site/what-is-choreo/index.html b/en/site/what-is-choreo/index.html deleted file mode 100644 index f8351895a..000000000 --- a/en/site/what-is-choreo/index.html +++ /dev/null @@ -1,3147 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - What is Choreo? - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
                                                  - - - -
                                                  - - - - - - -
                                                  - - -
                                                  - -
                                                  - - - - - - - -
                                                  -
                                                  - - - -
                                                  -
                                                  -
                                                  - - - - -
                                                  -
                                                  -
                                                  - - - -
                                                  -
                                                  -
                                                  - - - -
                                                  -
                                                  -
                                                  - - - -
                                                  -
                                                  - - - - - - - - - - - - - - - - - - - - -

                                                  What is Choreo?

                                                  -

                                                  Choreo is an internal developer platform that redefines how you create digital experiences. Choreo empowers you to seamlessly design, develop, deploy, and govern your cloud native applications, unlocking innovation while reducing time-to-market.

                                                  -

                                                  The following are some of the cutting-edge capabilities of Choreo:

                                                  -
                                                    -
                                                  • -

                                                    Design that leads to end-to-end security, governance, and operational efficiency:

                                                    -
                                                      -
                                                    • Domain-driven design: Organize your enterprise systems into domains, exposing managed APIs, events, and data through projects., A project consists of components representing units of deployment.
                                                      • -
                                                    • Application security design: Cell-based architecture, where projects become governable units from development to deployment, ensuring managed access via APIs, events, and data.
                                                      • -
                                                    -
                                                    • -
                                                  • -

                                                    Efficient and effective development:

                                                    -
                                                      -
                                                    • Code in any language: Develop applications in your team's preferred programming language, harnessing existing skill sets to build powerful polyglot APIs, services, events, tasks, and more.
                                                      • -
                                                    • Native support for VS Code: Seamlessly collaborate and manage code using VS Code in a feature-rich, visually-enhanced development environment.
                                                      • -
                                                    • Git repository integration: Effortlessly connect to Git-based platforms like GitHub, Bitbucket, or GitLab to develop components by linking an existing repository.
                                                      • -
                                                    -
                                                    • -
                                                  • -

                                                    Seamless deployment:

                                                    -
                                                      -
                                                    • CI/CD: Eliminate manual builds and unreliable deployments with Choreo's industry-standard CI/CD tooling, providing complete control and flexibility.
                                                      • -
                                                    • Multi-cloud Kubernetes: Easily deliver cloud native applications across Azure, AWS, GCP, or your Kubernetes clusters.
                                                      • -
                                                    • Configuration management: Centralize configuration parameters, sensitive credentials, and secrets across deployment environments via an intuitive interface.
                                                      • -
                                                    -
                                                    • -
                                                  • -

                                                    Effortless management of APIs, integrations, microservices, and web applications:

                                                    -
                                                      -
                                                    • Enable security: Empower security teams to manage data flows, ensuring seamless control over sensitive information like access credentials.
                                                      • -
                                                    • Scale up or down: Kubernetes handles scaling automatically, optimizing costs by scaling services based on demand.
                                                      • -
                                                    • Ensure reliability: DevOps and SRE teams can easily manage deployed components with built-in insights and observability.
                                                      • -
                                                    -
                                                    • -
                                                  • -

                                                    Reusable digital assets:

                                                    -
                                                      -
                                                    • Control visibility and sharing: Publish your digital assets to a shared marketplace for consumption by internal or external stakeholders, managed by role-based access control.
                                                      • -
                                                    • Internal Marketplace: Choreo's secure internal marketplace fosters transparency and efficiency with granular access control for publishers and consumers.
                                                      • -
                                                    -
                                                    • -
                                                  • -

                                                    Comprehensive observability:

                                                    -
                                                      -
                                                    • Anomaly detection: Stay ahead of issues with prompt notifications, ensuring balanced scaling and immediate action during unexpected mishaps.
                                                      • -
                                                    • Troubleshoot and debug: Quickly pinpoint and address root causes using detailed logs and data aligned in the same timeline, down to the machine-level details.
                                                      • -
                                                    -
                                                    • -
                                                  • -

                                                    Robust governance:

                                                    -
                                                      -
                                                    • DORA metrics: Monitor your DevOps efficiency with Choreo DORA metrics, experiencing rapid improvements in time from deployment to production safely and robustly.
                                                      • -
                                                    • Engineering insights: Gain visibility into engineering insights and advanced data analytics to make data-driven decisions, optimize processes, and improve efficiency.
                                                      • -
                                                    • API analytics: Understand API performance and adoption patterns to identify and resolve operational bottlenecks.
                                                      • -
                                                    -
                                                    • -
                                                  - - - - - - -
                                                  -
                                                  - - -
                                                  - - - -
                                                  - - -
                                                  - - - -
                                                  -
                                                  -
                                                  - - - - - - - - - - - - - - - - - \ No newline at end of file diff --git a/en/theme/material/partials/header.html b/en/theme/material/partials/header.html index 89f9513be..dd7941155 100644 --- a/en/theme/material/partials/header.html +++ b/en/theme/material/partials/header.html @@ -15,6 +15,7 @@ + {% include "partials/perspective-selector.html" %}
                                                  diff --git a/en/theme/material/partials/perspective-selector.html b/en/theme/material/partials/perspective-selector.html new file mode 100644 index 000000000..84ab59150 --- /dev/null +++ b/en/theme/material/partials/perspective-selector.html @@ -0,0 +1,150 @@ +{% if config.extra.show_perspective_dropdown %} +
                                                  + + {% set pe_path = config.pe_docs_path | d('/choreo/docs/platform-engineer') %} + + + +
                                                  + Developer + Platform Engineer +
                                                  +
                                                  +{% endif %} + + + + diff --git a/en/theme/material/templates/home-page-2.html b/en/theme/material/templates/home-page-2.html index 305350007..42edb04f9 100644 --- a/en/theme/material/templates/home-page-2.html +++ b/en/theme/material/templates/home-page-2.html @@ -19,6 +19,7 @@ + {% include "partials/perspective-selector.html" %}
                                                  @@ -405,8 +406,7 @@

                                                  - Develop an API Proxy -

                                                  + Develop an API Proxy
                                                  diff --git a/en/site/index.html b/en/theme/material/templates/pe-home-page.html similarity index 58% rename from en/site/index.html rename to en/theme/material/templates/pe-home-page.html index d1ee3dfdc..cdbc53066 100644 --- a/en/site/index.html +++ b/en/theme/material/templates/pe-home-page.html @@ -1,227 +1,78 @@ - +{% extends "base.html" %} +{% import "partials/language.html" as lang with context %} - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
                                                  - -
                                                  -
                                                  - -
                                                  - - - - - - - -
                                                  -
                                                  @@ -675,43 +611,9 @@

                                                  -
                                                  -
                                                  -
                                                  -
                                                  - Copyright © WSO2 LLC (2023-2024) -
                                                  -
                                                  - Content licensed under CC By 4.0. | Sample code - licensed under Apache 2.0. -
                                                  -
                                                  -
                                                  -
                                                  -

                                                  - - -
                                                  -
                                                  -
                                                  -
                                                  - - - - - - - - - - - - - - - - - \ No newline at end of file +