From 228a06b876300bf2c3984c9f6b79aa95aef20af0 Mon Sep 17 00:00:00 2001 From: jbirddog <100367399+jbirddog@users.noreply.github.com> Date: Tue, 6 Jun 2023 13:21:08 -0400 Subject: [PATCH] Start of DevOps/Connector Proxy docs (#301) * WIP, moving over connector proxy docs * Updated docs --- .../devops_guide/configure_connector_proxy.md | 47 +++++++++++++++ docs/devops_guide/deploy_aws_lambda.md | 59 +++++++++++++++++++ docs/index.md | 7 +++ 3 files changed, 113 insertions(+) create mode 100644 docs/devops_guide/configure_connector_proxy.md create mode 100644 docs/devops_guide/deploy_aws_lambda.md diff --git a/docs/devops_guide/configure_connector_proxy.md b/docs/devops_guide/configure_connector_proxy.md new file mode 100644 index 000000000..303ddea2e --- /dev/null +++ b/docs/devops_guide/configure_connector_proxy.md @@ -0,0 +1,47 @@ +# Configure a Connector Proxy + +## Setting the Environment Variable + +Once a `Connector Proxy` has been deployed, to integrate it with SpiffArena we simply need to update an environment variable and restart the backend. If using the [Getting Started Guide](https://www.spiffworkflow.org/posts/articles/get_started/) open the docker-compose.yml file, else edit the environment variable in the way appropriate for your deployment. The variable we need to change is called `SPIFFWORKFLOW_BACKEND_CONNECTOR_PROXY_URL`. + +Example diff using the function URL from the AWS tutorial: + +``` +diff --git a/docker-compose.yml b/docker-compose.yml +index 95b87b39..7d55c492 100644 +--- a/docker-compose.yml ++++ b/docker-compose.yml +@@ -26,7 +26,7 @@ services: + SPIFFWORKFLOW_BACKEND_URL: "http://localhost:${SPIFF_BACKEND_PORT:-8000}" + + SPIFFWORKFLOW_BACKEND_BPMN_SPEC_ABSOLUTE_DIR: "/app/process_models" +- SPIFFWORKFLOW_BACKEND_CONNECTOR_PROXY_URL: "http://spiffworkflow-connector:8004" ++ SPIFFWORKFLOW_BACKEND_CONNECTOR_PROXY_URL: "https://crbxgaopinfxqscntkqixjbl4e0gigpm.lambda-url.us-east-1.on.aws" + SPIFFWORKFLOW_BACKEND_DATABASE_URI: "mysql+mysqlconnector://root:${SPIFF_MYSQL_PASS:-my-secret-pw}@spiffworkflow-db:${SPIFF_MYSQL_PORT:-8003}/spiffworkflow_backend_development" + SPIFFWORKFLOW_BACKEND_LOAD_FIXTURE_DATA: "false" + SPIFFWORKFLOW_BACKEND_OPEN_ID_CLIENT_ID: "spiffworkflow-backend" + +``` + +Restart: + +``` +docker compose down +docker compose up -d +``` + +## Testing + +Create a new process model as described in the [Getting Started Guide](https://www.spiffworkflow.org/posts/articles/get_started/). Add a `Service Task` and in its properties panel you will see a drop down to pick which connector in your `Connector Proxy` to call. In this demo we deployed http get and post connectors: + +![Screenshot from 2023-04-06 16-38-02](https://user-images.githubusercontent.com/100367399/230489492-63cf88bf-7533-4160-95cb-d6194506dd5d.png) + +Choose the `http/GetRequest` operator ID and enter the [dog fact api](https://dog-api.kinduff.com/api/facts) URL. Remember to quote it since parameters are evaluated as Python expressions. + +![Screenshot from 2023-04-06 16-50-42](https://user-images.githubusercontent.com/100367399/230491661-abdfdd3a-48f5-4f50-b6e5-9e3a5f562961.png) + +Run the process and once complete you can see the response in the workflow: + +![Screenshot from 2023-04-06 16-49-53](https://user-images.githubusercontent.com/100367399/230491713-9d3f9bd0-f284-4004-b00c-cb6dc94b53df.png) + +You have successfully configured a `Connector Proxy` for use with `SpiffArena`. You made a call from a workflow to get a dog fact. Now imagine that call was to talk to an external system relevant to your business processes. diff --git a/docs/devops_guide/deploy_aws_lambda.md b/docs/devops_guide/deploy_aws_lambda.md new file mode 100644 index 000000000..006d08622 --- /dev/null +++ b/docs/devops_guide/deploy_aws_lambda.md @@ -0,0 +1,59 @@ +# Deploying a Connector Proxy as an AWS Lambda Function + +This guide shows you how to deploy the demo `Connector Proxy` as an `AWS Lambda Function` as well as how to integrate it with [SpiffArena](https://www.spiffworkflow.org/pages/spiffarena/). The [Getting Started Guide](https://www.spiffworkflow.org/posts/articles/get_started/) will be used as the basis for integration but the steps should easily map to any custom installation. + +There is an assumption that you have access to login to the AWS Console and can create/deploy Lambda functions. + +## Building the zip + +One option when deploying a Lambda function is to upload a zip file containing the source code or executable. In the root of [this repository](https://github.com/sartography/connector-proxy-lambda-demo) run: + +``` +make zip +``` + +This will create a zip file containing the [lambda entry point function](https://github.com/sartography/connector-proxy-lambda-demo/blob/main/connector_proxy_lambda_demo/lambda_function.py#L5) as well as all the dependencies needed to execute the connectors. For this example the libraries [spiffworkflow-proxy](https://github.com/sartography/spiffworkflow-proxy) is used for discovering connectors and [connector-http](https://github.com/sartography/connector-http) is an example connector that provides http get and post requests. + +Once `make zip` completes `connector_proxy_lambda_demo.zip` will be available in the repository root. + +## Creating the Lambda Function + +Log in to the AWS Console and navigate to the Lambda section. + +![Screenshot from 2023-04-06 15-19-35](https://user-images.githubusercontent.com/100367399/230482600-bf5f72b4-f499-4d44-8f6b-814d8e4c67d2.png) + +From there choose `Create function`. + +![Screenshot from 2023-04-06 15-22-39](https://user-images.githubusercontent.com/100367399/230482607-ad561180-9a4d-4ad1-8e4c-c97903f99100.png) + +Choose to `Author from scratch` and select the most recent Python runtime. + +![Screenshot from 2023-04-06 15-23-19](https://user-images.githubusercontent.com/100367399/230482609-8bece818-a41f-4f37-99c4-d9d10bef4d54.png) + +Under `Advanced Settings` check `Enable function URL`. For this demo we will use the `NONE` auth type to keep things simple. + +![Screenshot from 2023-04-06 15-24-12](https://user-images.githubusercontent.com/100367399/230482613-8fa6c8ef-5035-4a77-9670-f7211bf92cc0.png) + +After hitting the `Create function` button you will be taken to your new Lambda function: + +![Screenshot from 2023-04-06 16-02-11](https://user-images.githubusercontent.com/100367399/230482618-cf4cf088-3629-4832-9a3d-d81f29842aff.png) + +In the bottom right of the first section is a link to your Lamba's function URL. Click it for a hello world response. + +![Screenshot from 2023-04-06 16-09-08](https://user-images.githubusercontent.com/100367399/230484874-7529b786-da15-4a2c-8731-3780712bc0ef.png) + +## Deploying the Lambda Function + +If you scroll down you will see a section with the example code created with your Lambda function. We are going to replace this with the contents of our zip file. Choose `Upload from` and select `.zip file`. + +![Screenshot from 2023-04-06 16-09-34](https://user-images.githubusercontent.com/100367399/230484774-c0b93e1a-e34d-47b3-813f-03598d5bd631.png) + +After a confirmation dialog you will see your lambda has been updated: + +![Screenshot from 2023-04-06 16-12-05](https://user-images.githubusercontent.com/100367399/230485279-425e71ca-1c7f-4da3-b5e0-2fd2a464d746.png) + +Click your function URL again to see a hello from our deployed Connector Proxy. + +## Integrating With SpiffArena + +Congrats, your Connector Proxy has been deployed as a Lambda function. For information on configuring SpiffArena to use the new Connector Proxy url please see [Configure a Connector Proxy](configure_connector_proxy). \ No newline at end of file diff --git a/docs/index.md b/docs/index.md index d888b1d42..e6f0b3abe 100644 --- a/docs/index.md +++ b/docs/index.md @@ -14,6 +14,13 @@ admin_guide/admin_guide.md how_to/bpmn_unit_tests.md ``` +```{toctree} +:maxdepth: 2 +:caption: DevOps +devops_guide/configure_connector_proxy.md +devops_guide/deploy_aws_lambda.md +``` + ```{toctree} :maxdepth: 2 :caption: Contributing