Sample Scenario

This section describes an end-to-end real-life scenario that shows how to:

  1. Run the sample XEServer-based application (demo web service) without authorization.
  2. Add XEConnect OAuth2 Authorization capabilities to the demo web service.
  3. Use XESManager to monitor XEServer profiles operating inside Kubernetes.

Prerequisites

To perform the steps below, you will need the following:

  • The demo-with-auth.tar configuration package that includes all required configurations for sample deployments discussed in this section.
  • A Kubernetes cluster (1.20+). In this scenario, Docker Desktop with enabled Kubernetes and WSL is used.

    Note A minikube-powered cluster cannot be used for this scenario.

  • The Edifecs Google Container Registry credentials. To get the credentials, contact Edifecs Customer Support.
  • The XEServer license file.
  • cURL utility.

Run a demo web service without authorization

First, run the demo web service in Kubernetes without any authorization attached by following the steps below.

  1. Download and unzip demo-with-auth.tar:

    tar zxf demo-with-auth.tar

  2. Attach your Edifecs GCR credentials to the Kubernetes cluster as described in the Welcome email.
  3. Create a new service account:

    kubectl create serviceaccount edifecs-registry-reader

  4. (Optional) Create a secret for your dedicated Docker Hub account if you have one.

    kubectl create secret docker-registry <yourDockerHubAccount> --docker-server=https://index.docker.io/v2/ --docker-username=<yourDockerHubUsername> --docker-password='<yourPassword>' --docker-email=<your_email>

    This step is recommended due to Docker Hub's restrictions for unauthenticated pull requests.

  5. Update the service account to include the image pull secrets to access Docker registries.

    Update the service account to include the image pull secrets to access Docker Registries:

    kubectl patch serviceaccount edifecs-registry-reader -p '{"imagePullSecrets": [{"name": "edifecs-registry-key", "name": " <yourDockerHubAccount>"}]}'

    kubectl patch serviceaccount edifecs-registry-reader -p '{"imagePullSecrets": [{"name": "edifecs-registry-key"}]}'

Use XEServer license

  1. Attach the XEServer license to your cluster:

    kubectl create secret generic xes-license --from-file=license.lic

    Tip If you use the WSL shell, type sensible-browser and press ENTER. This opens a browser window to which you can drag-and-drop your XEServer license file (.lic).

Map TCP ports

  1. Create an Ingress controller to enable access to your cluster via the 443 port:

    kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/controller-v1.3.0/deploy/static/provider/cloud/deploy.yaml && kubectl wait --for=condition=available deployment --timeout 20s -n ingress-nginx ingress-nginx-controller;

  2. Attach the sample repository:

    kubectl create configmap repository --from-file=demo/xes-sample/xes_92_server_sample_restful_ws.zip

  3. Expose the port 443 attached to the Ingress controller:

    On Windows:

    kubectl expose deploy -n ingress-nginx ingress-nginx-controller --name nginx --port 443 --target-port 443;

    After you run the command, if a Windows Defender alert pops up, click Allow access.

    On Linux:

    kubectl expose deploy -n ingress-nginx ingress-nginx-controller --name nginx --port 443 --target-port 443 --external-ip `hostname -i`

  4. Allow the connection from the host machine to the cluster through the 443 port (may require root privileges):

    kubectl port-forward -n ingress-nginx service/nginx --address 0.0.0.0 443:443 &

Deploy the sample XEServer application

  1. Execute shared manifests that create necessary persistent volumes and initialize XEServer-related Kubernetes resources:

    kubectl apply -f demo/shared

  2. Deploy the demo web service (may take several minutes to complete):

    kubectl apply -k demo/xes-sample && kubectl wait --for=condition=available --timeout 240s deployment xes-sample

    ingress.networking.k8s.io/xes-sample created
    service/xes-sample created
    deployment.apps/xes-sample created

  3. Verify that the xes-sample deployment is ready:

    $ kubectl get pod
    NAME                              READY   STATUS      RESTARTS   AGE
    authorization-initializer-fd9gm   0/1     Completed   0          7m3s
    xes-sample-68c9c68b47-6klp5       1/1     Running     0          2m2s

  4. Set the IP or the host name of your cluster's Ingress endpoint as an environment variable. For example, the following name is available for Docker Desktop out of the box:

    export K8S_ENDPOINT=kubernetes.docker.internal;

Submit test data without authorization

  1. Submit test data for validation.

    rm output_result.zip > /dev/null 2>&1; curl -k -X POST --data-binary @demo/xes-sample/5010_270_x279_A1.dat -H "Content-Type: text/plain" -o output_result.zip https://$K8S_ENDPOINT/rest

    As a result, in your working directory, you get a ZIP archive (~12kB) output_results.zip with various reports (Audit XML/HTML, Splitting results, Acknowledgments) indicating the demo web service is running properly inside Kubernetes.

Enable authorization for the demo web service

To add XEConnect-based OAuth-authorization to the demo web service, follow the steps below:

  1. Enable authorization by setting the property AuthType=OAuth for the deploy/xes-sample pod. The modification of the property is a trigger for Kubernetes to restart the pod.

    kubectl set env deploy/xes-sample AuthType=OAuth && sleep 5 && kubectl get pod

    The new deployment spinning up may take several minutes to complete before the new deployment changes its readiness status from "0/1" to "1/1" and the old deployment gets terminated:

    NAME                              READY   STATUS      RESTARTS   AGE
    authorization-initializer-fd9gm   0/1     Completed   0          17m
    xes-sample-68c9c68b47-6klp5       1/1     Running     0          12m
    xes-sample-8b47ddc74-xwfm9        0/1     Running     0          29s

  2. Submit test data for validation again.

    curl -v -k -X POST --data-binary @demo/xes-sample/5010_270_x279_A1.dat -H "Content-Type: text/plain" -o output_result.zip https://$K8S_ENDPOINT/rest

    This returns a 401 Unauthorized response because the newly started demo web service requires authorization at this time.

Database Connectivity Setup

Deploy a database engine as a stateful set for the XEConnect Authorization service to operate. In this scenario, an instance of MS SQL Server runs in the same cluster for demonstration purposes. Alternatively, an external database can be provided which is recommended for production workloads.

  1. Create a new database to be used by XEConnect.
  2. Execute the script XEConnect\sql-scripts\xec-oauth-service\tables_sqlserver.sql.
  3. Apply the following configurations to your Kubernetes cluster:

    kubectl create secret generic external-db --from-literal=url=jdbc:jtds:sqlserver://<SQL_SERVER*>:1433/<DEMO_DB> --from-literal=username=<DEMO_DB_USER> --from-literal=password=`cat db.password`

    where a db.password file contains the database password. For security reasons, passwords should not be provided directly in the command line. Skip this step, if you use an external DB.

  1. Execute the manifest to launch an MSSQL DB in the cluster and create database structures required for XEConnect (the database operation is performed under the "sa" DB user):

    kubectl apply -f demo/shared/mssql-demo

  2. Attach sample XEConnect Account Management and Authorization sample profiles to the cluster. Alternatively, this profiles can be provided from a shared location (check with your cluster admin):

    kubectl create configmap xec-repository --from-file=demo/xec/sample-profiles

  3. Deploy XEConnect Account Management and Authorization sample profiles (it may take several minutes to complete):

    kubectl apply -k demo/xec && kubectl wait --for=condition=available --timeout 240s deployment account-management && kubectl get pod


    NAME                              READY   STATUS      RESTARTS   AGE
    account-management-b978b9cb4-9b8b9     1/1     Running     0     2m
    account-management-initializer-qzcf9   0/1     Completed   0     111s
    authorization-5969b66d74-ws8vp         1/1     Running     0     111s
    authorization-initializer-fd9gm        0/1     Completed   0     46m
    create-xec-accounts-db-2rpcz           0/1     Completed   0     110s
    mssql-0                                1/1     Running     0     5m1s
    mssql-init-dqgqv                       0/1     Completed   0     5m1s
    xes-sample-8b47ddc74-xwfm9             1/1     Running     0     29m

  4. Run the script that creates a sample OAuth client through the Account Management service API. The sample client account is stored in the MS SQL database:

    demo/xec/create-client.sh

  5. Using the client credentials created in the previous step (Client Credentials authorization flow), make anOAuth-authorized call:

    demo/xec/run-xes-sample.sh

    With the OAuth authorization enabled, the validation request passes the authorization and returns a ZIP archive (~12kB) with various reports (Audit XML/HTML, Splitting results, Acknowledgments), indicating that the demo web service has successfully authorized and processed data.

  6. You can use EAM to manage various clients that can be used for OAuth-authorization. If you executed step 19 to run a DB in the cluster, this DB can be accessed outside after you execute the following:

    kubectl expose deploy external-db --name mssql --port 1433 --target-port 1433

Use XESManager to monitor the activity of XEServer in pods

  1. Deploy the XEServer Agent and XEServer Manager (may take several minutes to complete):

    kubectl apply -k demo/xesm && kubectl wait --for=condition=available --timeout 20s sts xesm

  2. Open the XESManager web interface in the web browser using the $K8S_ENDPOINT that you have set previously:

    Using Windows bash emulator:

    start "" https://$K8S_ENDPOINT/xes-manager

    Using Windows WSL:

    sensible-browser https://$K8S_ENDPOINT/xes-manager

  3. View an XESManager page in your host machine's browser that displays details on the XEServer systems running as a part of the demo web service inside Kubernetes.